# Understanding the `explicit = true` Flag in uv Index Configuration for PyTorch

> Master PyTorch installations with uv index configuration. Learn how explicit = true ensures packages resolve strictly from your specified index, avoiding PyPI fallbacks and guaranteeing PyTorch wheels from the official CDN. Opt...

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

---

**Setting `explicit = true` in a `[[tool.uv.index]]` block designates that index as a dedicated source for specific packages only, preventing uv from falling back to PyPI and ensuring PyTorch wheels resolve exclusively from the official PyTorch CDN.**

The `baonguyen6742/uv-install-torch` repository demonstrates how to use **uv** (an extremely fast Python package manager) to install PyTorch from custom package indexes. When configuring alternative indexes in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml), the **`explicit = true` flag in uv index configuration** determines whether an index acts as a fallback mirror or a primary, isolated source for specific dependencies.

## What Is the `explicit` Flag in uv?

In uv's index configuration, the `explicit` boolean flag controls how custom indexes participate in dependency resolution. According to the source configuration in [[`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml)](https://github.com/baonguyen6742/uv-install-torch/blob/master/pyproject.toml#L53-L62) (lines 53‑62), the repository defines two PyTorch-specific indexes:

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

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

```

The behavior differs significantly based on this setting:

- **`explicit = false` (default):** The index is considered a *fallback* mirror. If a package cannot be found on the standard PyPI index, uv searches the custom index as a secondary source.

- **`explicit = true`:** The index is *explicitly enabled*. Packages must reference this index in their `tool.uv.sources` mapping, and uv will **only** look up those specific packages from this index. Other packages (like `pandas` or `numpy`) continue to resolve from PyPI, and uv will not fall back to PyPI for the explicitly mapped packages.

## How `explicit = true` Works in PyTorch Projects

### Configuring Dedicated Indexes

PyTorch distributes pre-compiled wheels for specific CUDA versions through their own CDN at `download.pytorch.org` rather than PyPI. By marking these indexes as `explicit = true`, the configuration ensures that PyTorch wheels are never accidentally resolved from PyPI, which might host stale or incompatible versions.

### Mapping Packages to Indexes with `tool.uv.sources`

To utilize these explicit indexes, the repository maps PyTorch packages to their respective indexes in the [`[tool.uv.sources]`](https://github.com/baonguyen6742/uv-install-torch/blob/master/pyproject.toml#L38-L50) section (lines 38‑50):

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

```

Because the `pytorch-cpu` and `pytorch-cu124` indexes are `explicit = true`, uv will resolve `torch`, `torchvision`, and `torchaudio` **exclusively** from the chosen CDN based on the selected extra. This prevents accidental resolution of similarly-named wheels from the default repository.

## Installing PyTorch with Explicit Index Selection

The repository leverages optional dependencies (`extras`) to switch between CPU and CUDA builds. Run the following commands based on your hardware requirements:

```bash

# Install the CPU-only PyTorch stack

uv pip install .[cpu]

# Install the CUDA-12.4 PyTorch stack

uv pip install .[cu124]

```

Both commands read the [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) and select the matching entry in `tool.uv.sources` based on the chosen extra. Because the referenced indexes are `explicit = true`, uv resolves the PyTorch packages **only** from the corresponding CDN URL.

To verify which index uv consulted during installation, use verbose mode:

```bash
uv pip install .[cpu] -vv

```

Look for log lines indicating the index selection:

```

Using index pytorch-cpu (https://download.pytorch.org/whl/cpu) for torch

```

## Why Explicit Indexes Prevent Resolution Errors

PyTorch wheels are built against specific CUDA versions and platform architectures. Without the **`explicit = true` flag in uv index configuration**, uv might resolve a PyTorch package from PyPI if available, potentially resulting in:

- Installation of a CPU-only wheel when CUDA support was required
- Mismatched CUDA versions between the PyTorch library and system drivers
- Non-deterministic builds across different environments

By marking the PyTorch CDN indexes as `explicit = true`, the `baonguyen6742/uv-install-torch` project guarantees that the correct CPU- or CUDA-specific wheels are fetched directly from `download.pytorch.org`, ensuring deterministic builds and preventing accidental package mismatches.

## Summary

- **`explicit = true`** converts a custom index from a fallback mirror to a dedicated source for specific packages mapped in `tool.uv.sources`.
- In the `baonguyen6742/uv-install-torch` repository, this flag ensures PyTorch wheels resolve exclusively from the official PyTorch CDN rather than falling back to PyPI.
- The combination of explicit indexes and extra-based source selection provides a clean mechanism to choose between CPU and CUDA-12.4 builds.
- This configuration prevents version mismatches and guarantees reproducible installations across development and production environments.

## Frequently Asked Questions

### What happens if I omit `explicit = true` in my uv index configuration?

Without `explicit = true`, uv treats the custom index as a fallback. If a package name exists on both PyPI and your custom index, uv may install the PyPI version instead of your intended wheel, leading to incompatible binaries or missing CUDA support. For PyTorch specifically, this could result in installing a generic wheel instead of the CUDA-optimized version.

### Can I use explicit indexes for packages other than PyTorch?

Yes. Any Python package distributed through a private index or specific CDN can use `explicit = true`. Define the index in `[[tool.uv.index]]` with `explicit = true`, then map the package name to that index in `[tool.uv.sources]`. This isolates the package resolution to that specific index, preventing conflicts with PyPI versions.

### How do I verify which index uv used to install a package?

Run `uv pip install` with the `-vv` (very verbose) flag. The output displays which index was consulted for each package, showing lines like `Using index pytorch-cpu (https://download.pytorch.org/whl/cpu) for torch`. This confirms that the `explicit = true` configuration is working as intended.

### Do I need to mark all custom indexes as explicit?

No. Only mark indexes as explicit when they contain specific package versions that must not be mixed with PyPI results, such as PyTorch's CUDA-specific wheels. General mirrors or private repositories containing multiple unrelated packages often work better as fallback indexes with the default `explicit = false`, allowing normal PyPI fallback behavior for unmapped packages.