uv — Administrator & Developer Guide

1. Architecture Overview

uv is an extremely fast Python package and project manager written in Rust. It provides a single binary that replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv. The architecture is designed around a high-performance async pipeline with aggressive caching, parallel downloads, and a PubGrub-based dependency resolver.

Architecture Diagram

┌──────────────────────────────────────────────────────────────┐
│                         uv CLI (clap)                        │
│  ┌─────────┬──────────┬──────────┬────────┬───────┬────────┐ │
│  │  run    │  sync    │  lock    │  pip   │ tool  │ python │ │
│  │  add    │  remove  │  build   │ publish│ cache │ audit  │ │
│  └────┬────┴────┬─────┴────┬─────┴───┬────┴───┬───┴────┬───┘ │
│       │         │          │         │        │        │      │
│  ┌────▼─────────▼──────────▼─────────▼────────▼────────▼───┐ │
│  │                Command Dispatch Layer                    │ │
│  │              (crates/uv/src/commands/)                   │ │
│  └────┬──────────┬──────────┬───────────┬──────────┬───────┘ │
│       │          │          │           │          │          │
│  ┌────▼────┐ ┌───▼────┐ ┌──▼─────┐ ┌──▼────┐ ┌───▼──────┐  │
│  │Resolver │ │Client  │ │Install │ │Build  │ │Python    │  │
│  │(PubGrub)│ │(reqwest│ │Wheel   │ │Backend│ │Discovery │  │
│  │         │ │+retry) │ │        │ │+Front │ │+Download │  │
│  └────┬────┘ └───┬────┘ └──┬─────┘ └──┬────┘ └───┬──────┘  │
│       │          │          │          │          │          │
│  ┌────▼──────────▼──────────▼──────────▼──────────▼────────┐ │
│  │                     Cache Layer                         │ │
│  │               (crates/uv-cache/)                        │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  Cross-cutting: Auth, Config, Logging, Platform, Filesystem  │
└──────────────────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Data Flow: uv add requests

1. CLI parsing → AddArgs { packages: ["requests"], ... }
2. Workspace discovery → find pyproject.toml, load workspace
3. Modify pyproject.toml → append "requests" to [project.dependencies]
4. Resolution → PubGrub solver queries index, resolves all transitive deps
5. Lock → Write uv.lock with pinned versions, hashes, markers
6. Sync → Compare lockfile vs installed packages
7. Download → Parallel fetch of missing wheels/sdists to cache
8. Install → Extract wheels to .venv/lib/python3.x/site-packages/
9. Report → Print resolution summary and install stats

Data Flow: uv run python app.py

1. CLI parsing → RunArgs { command: "python", args: ["app.py"], ... }
2. Project discovery → find pyproject.toml
3. Lock check → verify uv.lock is current (unless --no-sync)
4. Sync → install any missing/changed packages
5. Environment setup → activate .venv, set VIRTUAL_ENV, PATH
6. Exec → replace process with `python app.py`

Note

The resolver uses a forking strategy to handle platform-specific dependencies. It can produce different dependency sets for different Python versions and platforms within a single lockfile. The fork-strategy setting controls whether to optimize for latest versions (requires-python) or fewest versions (fewest).

2. System Requirements

Build Requirements (from source)

Runtime Requirements (binary)

Supported Platforms

3. Configuration Reference

Configuration Files

Configuration Precedence

CLI flags (highest)
  ↓
Environment variables (UV_*)
  ↓
Project uv.toml / [tool.uv] in pyproject.toml
  ↓
User config (~/.config/uv/uv.toml)
  ↓
System config (/etc/xdg/uv/uv.toml or /etc/uv/uv.toml)
  ↓
Defaults (lowest)

Important

UV_NO_CONFIG=1 disables all configuration file loading. CLI flags and environment variables still apply.

Complete Settings Reference

Resolver Settings

Index Settings

Install Settings

Project Settings

Performance Settings

Network Settings

Publishing Settings

Python Management Settings

Audit Settings

Build Backend Settings ([tool.uv.build-backend])

PyTorch Settings

Note

The torch-backend and add-bounds settings are preview features. Enable with preview = true in uv.toml or UV_PREVIEW=1.

Complete Environment Variable Reference

Core Variables

Python Management Variables

Project Variables

Network Variables

Tool Variables

Index Variables

Build Variables

Publishing Variables

Resolution Variables

Audit Variables

Important

Boolean environment variables accept 1, true, yes (enabled) or 0, false, no (disabled). This is parsed by clap's BoolishValueParser.

4. Deployment & Scaling

Docker Deployment

Minimal Production Image

FROM python:3.12-slim AS base

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Install dependencies first (layer caching)
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable --compile-bytecode

# Copy application
COPY . .

CMD ["uv", "run", "python", "-m", "app"]

Multi-Stage Build

# Build stage
FROM ghcr.io/astral-sh/uv:latest AS builder
WORKDIR /app
COPY pyproject.toml uv.lock ./
COPY src/ src/
RUN uv sync --frozen --no-dev --compile-bytecode

# Runtime stage
FROM python:3.12-slim
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/src /app/src
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "app"]

Tip

Use --compile-bytecode in Docker builds to trade install time for faster cold starts. Use --frozen to prevent lockfile updates in CI.

CI/CD Integration

GitHub Actions

- name: Install uv
  uses: astral-sh/setup-uv@v4
  with:
    version: "0.11.7"

- name: Install dependencies
  run: uv sync --locked

- name: Run tests
  run: uv run pytest

- name: Publish (with trusted publishing)
  run: uv publish --trusted-publishing always

GitLab CI/CD

install:
  script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - uv sync --locked
    - uv run pytest

Caching Strategy

$UV_CACHE_DIR/
├── archive-v0/         # Extracted wheel content (COW-linked to installs)
├── built-wheels-v5/    # Locally-built wheels from source distributions
├── flat-index-v2/      # Metadata from --find-links sources
├── interpreter-v4/     # Python interpreter metadata cache
├── managed-pythons/    # Downloaded Python interpreters (via `uv python install`)
├── sdists-v8/          # Downloaded source distributions
├── simple-v15/         # Package index metadata (PEP 503 API responses)
├── wheels-v3/          # Downloaded pre-built wheels
└── CACHEDIR.TAG        # Marks directory as cache (backup tools skip)

Note

The cache is safe to share between concurrent uv processes. File locking prevents corruption. Use uv cache prune to remove unreferenced entries; use uv cache clean only when you need a full reset.

Air-Gapped / Offline Deployment

1. Populate cache on a connected machine:

   uv sync  # Downloads everything to cache
   

2. Copy cache to the air-gapped machine:

   rsync -a ~/.cache/uv/ target:~/.cache/uv/
   

3. Install offline:

   UV_OFFLINE=1 uv sync --frozen
   

Alternatively, use --find-links with a local directory of wheels:

uv pip install --find-links /path/to/wheels --no-index package

5. Operations

Storage Locations

Note

On macOS, uv prefers XDG directories (~/.cache/uv, ~/.local/share/uv) but falls back to the native Application Support/Caches paths for backward compatibility if those directories already exist.

Cache Management

# View cache location
uv cache dir

# View cache size (human-readable)
uv cache size --human

# Clean everything
uv cache clean

# Clean specific package
uv cache clean requests

# Prune unreferenced entries (safe, keeps referenced data)
uv cache prune

# Prune with CI cleanup (also removes managed Python installs)
uv cache prune --ci

Tip

In CI, use uv cache prune --ci at the end of pipelines to minimize cache size without losing frequently-used packages.

Monitoring and Diagnostics

# Verbose output (increasing levels)
uv -v sync       # Basic verbose
uv -vv sync      # Debug verbose
uv -vvv sync     # Trace verbose

# Show resolved settings
uv show-settings

# Show Python discovery
uv python find -v 3.12

# Debug pip operations
uv pip debug

Set RUST_LOG=uv=debug for granular Rust-level logging.

Lock File Management

The uv.lock file is a cross-platform lockfile. Key operations:

# Create/update lockfile
uv lock

# Verify lockfile matches pyproject.toml (CI check)
uv lock --check

# Upgrade all packages to latest compatible versions
uv lock --upgrade

# Upgrade specific package
uv lock --upgrade-package requests

# Export to requirements.txt
uv export --format requirements-txt

Warning

The uv.lock format is specific to uv and is not compatible with other tools' lockfiles. Use uv export to generate requirements.txt for interoperability.

6. Performance

Performance Characteristics

Tuning Parameters

Memory Allocator

uv uses jemalloc on Linux and mimalloc on other platforms via the uv-performance-memory-allocator crate. This provides significant performance improvements for the allocation-heavy resolver.

7. Security

Authentication Methods

Authentication Policy

Each index can have an auth-policy:

[[tool.uv.index]]
name = "private"
url = "https://private.pypi.example.com/simple"
auth-policy = "always"

TLS Configuration

• Default: Bundled Mozilla root certificates via webpki-root-certs
• System certificates: system-certs = true or UV_SYSTEM_CERTS=1
• Insecure hosts: allow-insecure-host = ["internal.example.com"]

Caution

allow-insecure-host disables TLS verification for the specified hosts. Only use in secure, trusted networks. This setting is intended for corporate environments with custom CAs that cannot be added to the system store.

Credential Redaction

The uv-redacted crate provides DisplaySafeUrl — a URL wrapper that automatically masks passwords in log output. All URLs are displayed as https://user:****@host/ in logs and error messages.

Dependency Confusion Protection

The default index-strategy = "first-index" prevents dependency confusion attacks by only using the first index that contains a given package. The resolver does not mix packages across indexes.

Hash Verification

uv.lock stores SHA-256 hashes for all distributions. During uv sync --locked, every downloaded file is verified against its hash. Use uv export --format requirements-txt to generate a hash-pinned requirements file.

Supply Chain

• Python downloads verified via checksums from python-build-standalone
• Package hashes verified against index metadata
• Trusted publishing uses OIDC (no long-lived tokens)
• uv audit checks against the GitHub Advisory Database

8. Developer Internals

Repository Structure

astral-sh/uv/
├── crates/                     # Rust workspace members (~60 crates)
│   ├── uv/                     # Main binary crate
│   │   ├── src/
│   │   │   ├── lib.rs          # Entry point, CLI dispatch
│   │   │   ├── settings.rs     # Settings resolution
│   │   │   ├── commands/       # Command implementations
│   │   │   │   ├── project/    # add, remove, lock, sync, run, init, etc.
│   │   │   │   ├── pip/        # pip-compatible commands
│   │   │   │   ├── tool/       # tool install, run, list, etc.
│   │   │   │   ├── python/     # python install, list, find, pin
│   │   │   │   ├── auth/       # login, logout, token
│   │   │   │   └── workspace/  # list, metadata
│   │   │   └── ...
│   │   └── tests/it/           # Integration tests (single-crate pattern)
│   ├── uv-cli/                 # CLI argument definitions (clap derive)
│   ├── uv-settings/            # Configuration file parsing
│   ├── uv-configuration/       # Runtime configuration types
│   ├── uv-resolver/            # PubGrub-based resolver
│   ├── uv-client/              # HTTP client + registry API
│   ├── uv-installer/           # Package install orchestration
│   ├── uv-install-wheel/       # Wheel extraction
│   ├── uv-build-frontend/      # PEP 517 build frontend
│   ├── uv-build-backend/       # uv's PEP 517 build backend
│   ├── uv-python/              # Python discovery and management
│   ├── uv-workspace/           # Workspace resolution
│   ├── uv-publish/             # Package publishing
│   ├── uv-audit/               # Vulnerability auditing
│   ├── uv-auth/                # Authentication
│   ├── uv-cache/               # Cache management
│   ├── uv-distribution-types/  # Index and distribution types
│   ├── uv-platform-tags/       # Wheel compatibility tags
│   ├── uv-pep440/              # Version parsing (PEP 440)
│   ├── uv-pep508/              # Dependency specifiers (PEP 508)
│   ├── uv-normalize/           # Package name normalization
│   ├── uv-scripts/             # PEP 723 script metadata
│   ├── uv-keyring/             # Cross-platform keyring
│   ├── uv-torch/               # PyTorch index management
│   ├── uv-tool/                # Tool lifecycle management
│   ├── uv-virtualenv/          # Virtual environment creation
│   ├── uv-fs/                  # Filesystem operations
│   ├── uv-git/                 # Git source handling
│   ├── uv-extract/             # Archive extraction
│   ├── uv-dirs/                # Directory resolution
│   ├── uv-state/               # Persistent state
│   ├── uv-static/              # Constants (env var names)
│   ├── uv-trampoline/          # Windows launcher (nightly Rust)
│   └── ...                     # More utility crates
├── python/uv/                  # Python wrapper package
├── docs/                       # MkDocs documentation source
├── test/                       # Test fixtures and ecosystem tests
├── scripts/                    # Benchmarks, scenarios, publishing tests
└── Cargo.toml                  # Workspace root

Architecture Deep Dive

Resolver (uv-resolver)

The resolver is based on PubGrub (via astral-pubgrub), a version-solving algorithm that provides:

• Backtracking: Efficiently explores the version space
• Error messages: Produces human-readable conflict explanations
• Forking: Handles platform-specific dependencies by splitting the resolution tree

Key types:

• ResolverState — the main resolution state machine
• ForkState — handles platform/Python version forks
• Lock — the lockfile data structure with all resolved packages
• Resolution — the final resolved dependency graph

The resolver queries package metadata via the uv-client HTTP layer, which caches responses in the simple-v15 cache bucket.

HTTP Client (uv-client)

Built on reqwest with astral-reqwest-retry middleware:

• Retry policy: Exponential backoff with jitter
• Connection pooling: Per-host connection reuse
• HTTP/2: Enabled by default for multiplexing
• Compression: Transparent gzip/deflate/zstd
• Caching: HTTP cache with If-Modified-Since / If-None-Match
• Proxy support: HTTP, HTTPS, SOCKS5 (via system proxy detection)
• Request signing: AWS (reqsign) for CodeArtifact, Google for Artifact Registry

Python Discovery (uv-python)

Python discovery follows a priority chain:

1. Virtual environment (VIRTUAL_ENV, .venv)
2. Managed installations (~/.local/share/uv/python/)
3. PATH search
4. Windows Registry (HKCU\Software\Python)
5. Windows Store Python

The PythonPreference enum controls ordering:

• managed — prefer managed, fall back to system
• system — prefer system, fall back to managed
• managed-only — only managed installations
• system-only — only system installations

Workspace (uv-workspace)

Workspace discovery walks up from the current directory to find the root pyproject.toml with [tool.uv.workspace]. Members are resolved via glob patterns:

[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/experimental"]

Each member gets its own lockfile resolution within the workspace-wide uv.lock.

Build System

Two components:

Build Frontend (uv-build-frontend): Implements PEP 517/518 build isolation. For each source distribution:

1. Creates a temporary venv with declared build dependencies
2. Calls build_wheel() or build_sdist() via the PEP 517 interface
3. Caches the result in built-wheels-v5

Build Backend (uv-build-backend): uv's own PEP 517 backend, used when pyproject.toml declares:

[build-system]
requires = ["uv>=0.5.15,<0.13"]
build-backend = "uv_build"

Features: src/flat layout support, namespace packages, sdist/wheel/editable builds, data includes.

Authentication (uv-auth)

The auth system supports multiple credential sources with a priority chain:

1. URL-embedded credentials (https://user:pass@host)
2. UV_INDEX_<NAME>_USERNAME / UV_INDEX_<NAME>_PASSWORD
3. Keyring (keyring-provider = "subprocess")
4. .netrc file
5. OIDC trusted publishing (GitHub Actions, GitLab CI)

The AuthPolicy per index controls behavior (auto, always, never).

The uv-keyring crate provides cross-platform keyring access:

• macOS: Keychain via security-framework
• Linux: Secret Service D-Bus API via secret-service
• Windows: Credential Manager via Windows API

Cache System (uv-cache)

The cache uses content-addressed storage with bucket-based organization:

• Cache keys: SHA-256 of URL, version, and platform metadata
• Link strategy: COW clones (APFS/Btrfs), hardlinks (NTFS/ext4), or copies
• Concurrency: File locks prevent corruption from parallel access
• Invalidation: cache-keys in pyproject.toml define rebuild triggers

The CacheEntry system tracks metadata alongside cached artifacts. The archive-v0 bucket contains pre-extracted wheel contents that can be directly linked into site-packages.

Code Patterns and Conventions

Build Profiles

Testing Strategy

uv uses a comprehensive testing approach:

• Unit tests: Per-crate, testing internal logic
• Integration tests: In crates/uv/tests/it/ — one main.rs binary (matklad pattern)
• Snapshot tests: insta for CLI output, resolver output, lockfile content
• Ecosystem tests: Real-world projects (airflow, black, transformers, etc.)
• Scenario tests: Generated from templates in scripts/scenarios/
• Feature-gated tests: test-python (needs Python), test-pypi (needs network), test-git (needs git)
• Benchmarking: Custom harness in scripts/benchmark/

# Run all tests
cargo test

# Run with required features
cargo test --features "test-python test-pypi"

# Run specific test
cargo test -p uv -- pip_install

# Update snapshots
cargo insta test --review

Contributing

# Clone and build
git clone https://github.com/astral-sh/uv
cd uv
cargo build

# Run the development binary
cargo run -- pip install requests

# Run pre-commit checks
pre-commit run --all-files

# Generate CLI reference (required when changing uv-cli or uv-settings)
cargo dev generate-all

# Run the formatter
cargo fmt

# Run clippy
cargo clippy --workspace --all-targets

Important

After modifying uv-cli or uv-settings, run cargo dev generate-all to regenerate the CLI reference, JSON schema, environment variables reference, and options reference. This is enforced by a pre-commit hook.

Potential Improvements

Based on source analysis:

• TODO in uv-auth/src/index.rs: The Indexes struct iterates linearly over all indexes for prefix matching; a trie would be more efficient for large index sets
• TODO in uv-auth/src/index.rs: Index duplicates uv_distribution_types::Index to avoid circular dependencies; future refactor could unify these
• Preview features system: The uv-preview crate supports per-feature granularity but many features are still gated by a single --preview flag
• Windows trampoline: The uv-trampoline crate requires nightly Rust due to #![no_std] + Windows PE manipulation

9. Integration Points

Package Index Protocol

uv implements PEP 503 (Simple Repository API) and PEP 691 (JSON-based API). It queries indexes in the format:

GET /simple/{package}/ HTTP/1.1
Accept: application/vnd.pypi.simple.v1+json, text/html;q=0.1

Build System Protocol

uv implements:

• PEP 517: Build backend interface (build_wheel, build_sdist, etc.)
• PEP 518: Build system requirements ([build-system] in pyproject.toml)
• PEP 660: Editable installs via build_editable
• PEP 723: Inline script metadata for uv run
• PEP 735: Dependency groups

Lockfile Format

uv.lock is a TOML-based format containing:

version = 1
requires-python = ">=3.11"

[[package]]
name = "requests"
version = "2.32.3"
source = { registry = "https://pypi.org/simple" }

[[package.dependencies]]
name = "certifi"
version = ">=2017.4.17"

[package.sdist]
url = "https://files.pythonhosted.org/..."
hash = "sha256:..."
size = 131218

[[package.wheels]]
url = "https://files.pythonhosted.org/..."
hash = "sha256:..."
size = 63928

Python Wrapper Package

The python/uv/ directory contains a Python package that provides:

• uv module that delegates to the Rust binary
• uv._find_uv for binary discovery
• __main__.py for python -m uv execution

Binary Distribution

uv ships three binaries:

• uv — the main binary
• uvx — alias for uv tool run
• uvw — Windows-only windowless variant (no console window)

Distribution via:

• Standalone installers (shell script, PowerShell)
• PyPI (pip install uv)
• Homebrew, Conda, Cargo
• Docker images (ghcr.io/astral-sh/uv)
• GitHub Releases (via cargo-dist)