Package Indexes and Index Strategy

Relevant source files

This page documents how uv manages package indexes, including configuration, resolution strategies, flat indexes, alternative indexes, and specialized handling for complex ecosystems like PyTorch.

Index Configuration and Models

In uv, an index is represented primarily by the Index struct, which encapsulates the URL, optional name, and behavioral flags such as explicit or default crates/uv-distribution-types/src/index.rs130-175

Key Data Structures

IndexUrl: An enum representing the location of an index. It can be a PyPI URL, a custom HTTP URL, or a local filesystem path. The IndexUrl abstracts these variants transparently crates/uv-distribution-types/src/index_url.rs31-35
Index: The complete index configuration entity includes metadata fields such as:
- name: Optional identifier to refer to an index elsewhere in the configuration.
- url: The actual endpoint or path of the index.
- explicit: Marks whether the index is explicit, meaning it will only be used if explicitly referenced via [tool.uv.sources] configuration crates/uv-distribution-types/src/index.rs130-175
VersionMap: A version-to-distributions mapping representing all known versions and available distribution files for a package on one index. It can be initialized lazily from Simple API metadata and optionally merged with flat index entries crates/uv-resolver/src/version_map.rs31-137
FlatIndex: Represents collections of distributions discovered from --find-links entries or alternative flat indexes. These are indexed by package name and version separately from PEP 503 simple API indexes crates/uv-resolver/src/flat_index.rs23-62

Conceptual Diagram: Configuration to Code Entities Mapping for Indexes

Sources: crates/uv-distribution-types/src/index.rs130-185 crates/uv-distribution-types/src/index_url.rs31-35 crates/uv-resolver/src/version_map.rs31-137 crates/uv-resolver/src/flat_index.rs23-62

Index Priority Strategies

uv supports different strategies to determine how packages are resolved when multiple indexes contain the same package. These strategies are critical to avoid dependency confusion and maintain consistency.

The IndexStrategy enum is configured via resolver options and used by the CandidateSelector during package candidate selection crates/uv-resolver/src/candidate_selector.rs25-29

Available Strategies

FirstIndex (Default)
- Iterates indexes in configured priority order.
- Stops at the first index containing the package.
- Only considers versions from that index thereafter.
This strategy is safer against attacks like dependency confusion by locking resolution to a single source and prevents cross-index version mixing.
UnsafeBestMatch
- Queries all indexes to find the "best" (usually highest) compatible version globally.
- Unsafe because a malicious package with a higher version number on a public index can override private package versions.

Explicit Indexes and Index Pinning

Indexes marked with explicit = true in the config are hidden from the global search by default. Packages on these indexes only appear if explicitly requested by pinning in [tool.uv.sources], to avoid polluting candidate sets with unrelated packages.

Internally, these mappings are tracked by the Indexes struct which uses a ForkMap<IndexMetadata> allowing resolver environment and marker-specific index selections crates/uv-distribution-types/src/index.rs149-164 crates/uv-resolver/src/resolver/indexes.rs19-53

Candidate Selection Logic for Indexes

Sources: crates/uv-distribution-types/src/index.rs149-164 crates/uv-resolver/src/candidate_selector.rs78-161 crates/uv-resolver/src/resolver/indexes.rs19-53

Flat Indexes and Alternative Indexes

Besides standard PEP 503-compliant registry indexes, uv supports flat indexes such as those provided by --find-links. These indexes contain direct file links rather than metadata organized by package.

The FlatIndex struct stores these entries organized by package name and version.
Flat index entries are integrated into package metadata during resolution to supplement or override index metadata.
They are parsed into PrioritizedDist objects that describe source distributions and built wheels with associated compatibility metadata, hash checks, and build constraints crates/uv-resolver/src/flat_index.rs23-62 crates/uv-resolver/src/version_map.rs139-160

Data Flow Diagram: Integrating Flat Index Entries in Version Maps

Sources: crates/uv-resolver/src/flat_index.rs23-62 crates/uv-resolver/src/version_map.rs139-160 crates/uv-resolver/src/candidate_selector.rs78-161

Package Index Metadata Fetching and VersionMap Construction

The DefaultResolverProvider is the main IO backend for resolver package metadata fetching crates/uv-resolver/src/resolver/provider.rs110-188

Metadata Fetch Process

DefaultResolverProvider::get_package_versions queries the index Simple API (/simple/<package>) via the RegistryClient
Receives archived serialized metadata (SimpleDetailMetadata) describing available versions and files.
Optionally merges FlatDistributions from flat indexes.
Constructs a VersionMap that stores lazily evaluated PrioritizedDist for each version, allowing efficient lookup and metadata deserialization on demand.
Manages yanked releases and availability cutoff timestamps as part of this process crates/uv-resolver/src/version_map.rs36-136 crates/uv-resolver/src/resolver/provider.rs172-188

Remote to Local VersionMap Data Flow

Sources: crates/uv-resolver/src/resolver/provider.rs172-188 crates/uv-resolver/src/version_map.rs37-136 crates/uv-resolver/src/flat_index.rs23-62

PyTorch Index Auto-Selection Strategy

The PyTorch ecosystem presents unique challenges:

PyTorch wheels are distributed across multiple dedicated indexes depending on accelerator type (CPU, CUDA versions, ROCm).
PyTorch package versions include local version identifiers (e.g., 2.11.0+cu130) that encode accelerator information.
There is no standard PEP 508 marker for accelerators, demanding dynamic selection logic.
Different indexes host different accelerator-specific builds which must be selected appropriately.

uv integrates with the uv-torch crate to automate index and variant selection based on the platform and GPU accelerator detected at runtime.

Accelerator Detection (`uv-torch::accelerator`)

The crate detects installed GPU accelerators using:

Environment variables:
- UV_CUDA_DRIVER_VERSION to override CUDA driver detection.
- UV_AMD_GPU_ARCHITECTURE to override AMD GPU architecture detection.
System files and commands:
- Linux NVIDIA driver version from /sys/module/nvidia/version or /proc/driver/nvidia/version.
- nvidia-smi command for CUDA driver version.
- rocm_agent_enumerator command to detect AMD ROCm GPU architecture.
PCI device enumeration on Linux and Windows for Intel GPUs (XPU) crates/uv-torch/src/accelerator.rs38-98

TorchMode Enum and Index Mapping

The TorchMode enum enumerates all accelerator options such as Auto, Cpu, and specific CUDA/ROCm versions.
When Auto is selected, uv-torch runs detection to pick the appropriate mode.
Each TorchMode corresponds to a distinctive PyTorch index URL, e.g., https://download.pytorch.org/whl/cu130 for CUDA 13.0 crates/uv-torch/src/backend.rs59-151

Integration Workflow

Sources: crates/uv-torch/src/accelerator.rs38-98 crates/uv-torch/src/backend.rs59-151 docs/guides/integration/pytorch.md20-130

Example PyTorch Index Configuration (from docs)

Example configuration in pyproject.toml specifying a CUDA 13.0 PyTorch index enabled on Linux and Windows:

This configuration ensures torch and torchvision use PyTorch's CUDA 13.0 wheels on Linux and Windows, falling back to PyPI on macOS.

Cache Control Overrides and Considerations

uv applies special cache-control policies to handle known quirks in some indexes:

Wheels hosted on download.pytorch.org and pypi.nvidia.com were incorrectly uploaded with HTTP headers disabling caching.
uv overrides these headers to allow very long cache lifetimes, improving reliability and performance for these wheels (e.g., "max-age=365000000, immutable, public") crates/uv-distribution-types/src/index.rs37-56

Users can configure per-index cache control headers via the IndexCacheControl struct, specifying separate controls for Simple API queries and file artifact downloads crates/uv-distribution-types/src/index.rs19-28

Summary Table of Concepts and Code Entities

Concept / Model	Code Entities	Description
Package Index URL	`IndexUrl` (enum)	Represents an index's URL or local path
Index Configuration	`Index` (struct)	Holds index metadata and behavioral flags
Index Priority Strategy	`IndexStrategy`, `CandidateSelector`	Strategy to prioritize indexes during resolution
Version Mapping	`VersionMap` (struct)	Maps versions to distributions per index
Flat Index	`FlatIndex` (struct)	Represents `--find-links` flat index entries
Package Metadata Fetch	`DefaultResolverProvider` (impl)	Fetches and assembles package metadata
PyTorch Accelerator Detection	`uv-torch::accelerator::Accelerator`	Detects GPU for PyTorch index auto-selection
PyTorch Index Selection	`uv-torch::backend::TorchMode`	Maps CTX & detection to PyTorch index URLs

Sources:
crates/uv-distribution-types/src/index.rs130-185
crates/uv-distribution-types/src/index_url.rs31-35
crates/uv-resolver/src/version_map.rs31-136
crates/uv-resolver/src/flat_index.rs23-62
crates/uv-resolver/src/candidate_selector.rs25-161
crates/uv-resolver/src/resolver/indexes.rs19-53
crates/uv-resolver/src/resolver/provider.rs110-188
crates/uv-torch/src/accelerator.rs38-98
crates/uv-torch/src/backend.rs59-151
docs/guides/integration/pytorch.md20-130
crates/uv-distribution-types/src/index.rs19-56
crates/uv-distribution-types/src/index.rs95-125