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

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, 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/master/pyproject.toml#L53-L62) (lines 53‑62), the repository defines two PyTorch-specific indexes:

[[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] section (lines 38‑50):

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

# 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 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:

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.

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