# Installing Specific torchvision and torchaudio Versions Matching PyTorch with uv

> Easily install specific torchvision and torchaudio versions that match your PyTorch build using uv. Configure pyproject.toml and sync with uv sync for precise dependency management.

- Repository: [Th3Unknovvn/uv-install-torch](https://github.com/baonguyen6742/uv-install-torch)
- Tags: tutorial
- Published: 2026-02-26

---

**To install torchvision and torchaudio versions that exactly match your PyTorch build using uv, configure optional dependencies and dedicated source indexes in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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:

```toml
[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:

```toml
[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:

```toml
[[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:

```toml
[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:

```bash
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:

```bash
uv sync --extra cpu

```

## Verifying Version Alignment

The repository includes [`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py) (lines 1-44) to validate that the installed versions match and that CUDA tensors execute correctly:

```bash
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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) to update the pinned versions for all three packages simultaneously:

```toml
[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:

```bash
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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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.