Installing Specific torchvision and torchaudio Versions Matching PyTorch with uv

To install torchvision and torchaudio versions that exactly match your PyTorch build using uv, configure optional dependencies and dedicated source indexes in pyproject.toml to pin compatible wheel versions, then synchronize with uv sync --extra cu124 or uv sync --extra cpu.

Installing PyTorch alongside its ecosystem packages often results in runtime errors when torchvision or torchaudio resolve from PyPI while torch pulls from a CUDA-specific index. The baonguyen6742/uv-install-torch repository solves this by demonstrating a declarative, reproducible method for installing specific torchvision/torchaudio versions matching PyTorch using uv's advanced resolution features.

The PyTorch Version Alignment Challenge

PyTorch distributes CPU-only and CUDA-enabled wheels through separate indexes (download.pytorch.org). Standard package managers may resolve torch from the CUDA index while pulling torchvision from PyPI, creating ABI incompatibilities that surface as ImportError or silent runtime crashes. The repository's approach eliminates this risk by locking all three packages to the same build source.

Declarative Configuration in pyproject.toml

The solution centers on coordinated configuration across four sections of pyproject.toml (lines 24-62), ensuring uv fetches mutually compatible wheels from the correct index.

Pinning Versions with Optional Dependencies

Lines 24-28 define mutually exclusive extras that pin exact versions for each build variant:

[project.optional-dependencies]
cpu = ["torch==2.4.1", "torchvision==0.19.1", "torchaudio==2.4.1"]
cu124 = ["torch==2.4.1", "torchvision==0.19.1", "torchaudio==2.4.1"]

By hard-pinning versions within the extras, you guarantee that activating cu124 installs torchvision==0.19.1+cu124 rather than a generic PyPI build.

Mapping Extras to Source Indexes

Lines 38-50 in the [tool.uv.sources] section direct uv to pull each package from the PyTorch wheels index matching the selected extra:

[tool.uv.sources]
torch = [
  { extra = "cpu", index = "pytorch-cpu" },
  { extra = "cu124", index = "pytorch-cu124" },
]
torchvision = [
  { extra = "cpu", index = "pytorch-cpu" },
  { extra = "cu124", index = "pytorch-cu124" },
]
torchaudio = [
  { extra = "cpu", index = "pytorch-cpu" },
  { extra = "cu124", index = "pytorch-cu124" },
]

This mapping ensures that selecting --extra cu124 pulls all three packages from the CUDA 12.4 index, maintaining ABI consistency.

Explicit Index Declaration

Lines 53-62 declare the concrete URLs with explicit = true to prevent uv from falling back to PyPI for these packages:

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"
explicit = true

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

The explicit flag forces uv to use only the declared index for packages mapped to it in [tool.uv.sources], eliminating the risk of mismatched metadata.

Conflict Prevention

Lines 30-33 guarantee that a user cannot install both CPU and CUDA variants simultaneously:

[tool.uv]
conflicts = [
  { extra = "cpu" },
  { extra = "cu124" },
]

This declaration prevents resolution graphs that might attempt to merge incompatible torch builds.

Installing the Matched Stack

To install the CUDA 12.4 stack with matching torchvision and torchaudio versions:

uv sync --extra cu124

uv reads the cu124 extra from lines 24-28, resolves the exact pins, and fetches all three packages from the pytorch-cu124 index defined in lines 53-62. Dependencies like opencv or pandas resolve from PyPI as usual.

For CPU-only installations:

uv sync --extra cpu

Verifying Version Alignment

The repository includes main.py (lines 1-44) to validate that the installed versions match and that CUDA tensors execute correctly:

uv run main.py

Expected output confirms the synchronized builds:

torch.__version__: 2.4.1+cu124
torchvision.__version__: 0.19.1+cu124
torchaudio.__version__: 2.4.1+cu124
torch.cuda.is_available: True

Device 0 : _CudaDeviceProperties(name='NVIDIA GeForce RTX 3060', ...)
Test calculation
tensor([[1, 2, 3],
        [2, 4, 6]], device='cuda:0')

Updating to Newer PyTorch Versions

When upgrading (e.g., from 2.4.1 to 2.5.0), edit lines 24-28 in pyproject.toml to update the pinned versions for all three packages simultaneously:

[project.optional-dependencies]
cu124 = ["torch==2.5.0", "torchvision==0.20.0", "torchaudio==2.5.0"]

Then re-run uv sync --extra cu124. The index URLs remain unchanged; uv fetches the new wheels from the same source.

Troubleshooting Cache Issues

If uv resolves incorrect versions after changing extras, clear the cache to remove stale wheels:

uv cache clean torch
uv cache prune
uv sync --extra cu124

Summary

• Pin exact triples：Define torch, torchvision, and torchaudio with explicit versions in [project.optional-dependencies] to prevent mismatches.
• Map to indexes：Use [tool.uv.sources] to route each extra to the correct PyTorch wheels index (CPU or CUDA).
• Block PyPI fallback：Set explicit = true in [tool.uv.index] to ensure uv never mixes PyPI builds with PyTorch index builds.
• Prevent conflicts：Declare [tool.uv.conflicts] to stop simultaneous installation of incompatible variants.
• Synchronize：Run uv sync --extra cu124 (or cpu) to install the matched stack reproducibly.

Frequently Asked Questions

How do I ensure torchvision matches my PyTorch CUDA version when using uv?

Configure [tool.uv.sources] in pyproject.toml to map the cu124 extra to the pytorch-cu124 index, and pin exact versions in [project.optional-dependencies]. This forces uv to resolve all three packages from the same CUDA-enabled index rather than mixing PyPI and PyTorch builds.

Can I install both CPU and CUDA versions in the same environment?

No. The conflicts declaration in pyproject.toml (lines 30-33) prevents uv from resolving both extras simultaneously, avoiding runtime clashes between CPU and CUDA binaries.

Why is explicit=true required in the index configuration?

Without explicit = true, uv may fall back to PyPI if the PyTorch index is temporarily unreachable or if metadata appears incomplete. This fallback risks installing a CUDA-enabled torch with a CPU-only torchvision from PyPI, causing runtime errors when importing the libraries.

What is the correct way to upgrade PyTorch versions with this setup?

Edit the version pins in the [project.optional-dependencies] section (lines 24-28) to update torch, torchvision, and torchaudio simultaneously to their new compatible versions. Then run uv sync --extra cu124 or uv sync --extra cpu to fetch the updated wheels from the configured indexes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}