Getting started

This page is for developers working on uv itself. End users should follow the installation guide in the product docs.

Prerequisites

To build uv from source you need:

• A Rust toolchain. The MSRV is rust-version = "1.93.0" per rust-toolchain.toml. Install via rustup.
• A C compiler:
  • Debian/Ubuntu: sudo apt install build-essential
  • Fedora: sudo dnf install gcc
  • macOS: Xcode Command Line Tools
• On Windows, NASM is required for the aws-lc-sys TLS backend (or set AWS_LC_SYS_PREBUILT_NASM=0 to use a prebuilt blob).
• Python 3.8+ on PATH for some scripts and tests, plus the Python versions listed in .python-versions for the full integration test matrix.

The full contributor setup is documented in CONTRIBUTING.md.

Build

uv is a Cargo workspace. From the repository root:

$ cargo build

This produces target/debug/uv and target/debug/uvx. To build the release binary use cargo build --release. The AGENTS.md file recommends avoiding the release profile during day-to-day work because of its long build times — it disables lto and strips debug info.

For benchmarking the profiling profile mirrors release but keeps debug info and skips LTO (see Cargo.toml for the rationale and timing comparisons).

Run a development build

You can invoke your local checkout directly with cargo run:

$ cargo run -- venv
$ cargo run -- pip install requests
$ cargo run -- run -- python -c "import sys; print(sys.executable)"

scripts/cargo.sh and scripts/cargo.cmd are convenience wrappers that forward to the workspace cargo. The scripts/bin/ directory holds shims that mimic uv's entry points without rebuilding.

Tests

uv uses cargo nextest plus insta for snapshot assertions. Most tests are integration tests that exec the uv binary and snapshot the output.

# Run a single named test
$ cargo nextest run -E 'test(test_name)'

# Run all tests and accept snapshot changes
$ cargo insta test --accept --test-runner nextest

# Update snapshots for a specific test
$ cargo insta test --accept --test-runner nextest -- <test_name>

Integration tests live under crates/uv/tests/it/. Per the project's AGENTS.md, integration tests are preferred over unit tests, and snapshot assertions (uv_snapshot!) are preferred over substring assertions.

Some tests need real Python interpreters; install them with:

$ cargo run python install

Set UV_PYTHON_INSTALL_DIR (an absolute path) if you want a different storage location.

A subset of tests requires Git and Git LFS; you can disable them by turning off the git or git-lfs features.

Lint and format

# Rust
cargo fmt --all
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

# Python (in `python/`, `scripts/`, etc.)
uvx ruff format .
uvx ruff check .
uvx ty check python/uv

# Markdown / YAML / JSON
npx prettier --write .

# Shell scripts
shellcheck <script>

# Spelling
uvx typos

# Unused Rust dependencies
cargo shear

The pre-commit hooks in .pre-commit-config.yaml wire most of these up.

To cross-check Windows compilation from Linux/macOS, install cargo-xwin and run cargo xwin clippy --workspace --all-targets --all-features --locked -- -D warnings.

Documentation

The user-facing docs live in docs/ and are built with mkdocs. To preview locally:

1. cargo dev generate-all — regenerates the auto-generated reference pages.
2. uv run --only-group docs mkdocs serve -f mkdocs.yml

Docs are deployed automatically on release by publishing to the astral-sh/docs repository.

Profiling and benchmarking

scripts/benchmark/ contains a uv package for benchmarking resolution and installation between uv versions and against pip / poetry / pdm. Example:

$ uv run resolver --uv-pip --poetry --benchmark resolve-cold ../test/requirements/trio.in

The tracing-durations-export feature in crates/uv/Cargo.toml writes per-span durations to a file that can be visualized with tracing-durations-export to find serialization bottlenecks.

Workspace tour

A quick orientation for first-time contributors:

Looking for…	Look in
The uv CLI's argument schema	crates/uv-cli/src/lib.rs
The implementation of a specific subcommand	crates/uv/src/commands/
Settings parsing	crates/uv/src/settings.rs
Dependency resolution	crates/uv-resolver/
The lockfile format	crates/uv-resolver/src/lock/mod.rs
Wheel installation	crates/uv-installer/, crates/uv-install-wheel/
Python interpreter discovery	crates/uv-python/src/discovery.rs
Managed Python downloads	crates/uv-python/src/downloads.rs, managed.rs
HTTP / cache	crates/uv-client/, crates/uv-cache/
pyproject.toml parsing	crates/uv-workspace/src/pyproject.rs

For a deeper tour, jump to Architecture or the crates index.