Development workflow

The day-to-day loop for working on uv is small: edit, build, run a focused test, snapshot, commit. This page captures the commands and conventions that make that loop fast.

Branches and PRs

uv lives at https://github.com/astral-sh/uv. The default branch is main. There are no long-lived feature branches; contributors typically push branches to their fork and open PRs against main.

Releases are cut from main by an Astral team member running ./scripts/release.sh, editorializing the auto-generated CHANGELOG.md entry, and opening a Bump version to ... PR. After merge, the release workflow is run with the version tag (no leading v). Binary builds are validated automatically. Crate publishing is handled by .github/workflows/publish-crates.yml.

Building

uv is a Cargo workspace. The most common commands:

# Default debug build
$ cargo build

# Just the binary
$ cargo build -p uv

# A specific crate
$ cargo build -p uv-resolver

Avoid the release profile during day-to-day work — Cargo.toml has a long comment explaining why: with lto = "fat" set, a single-crate edit can take 3–4 minutes to rebuild. There are several intermediate profiles for different needs:

Profile	When to use
dev (default)	Daily edits
fast-build	Faster test loop (opt-level = 1, no debug info)
no-debug	Fast builds with smaller binaries
profiling	Benchmarks; mirrors release but keeps debug info, no LTO
release	Real release builds only; lto = "fat", strip enabled
dist	Cargo-dist's release configuration
minimal-size	The uv-build binary, optimized for size

To run uv from source:

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

Quick edit / verify cycle

A typical change to a single crate:

1. Edit the relevant file (e.g., crates/uv-resolver/src/resolver/mod.rs).
2. Run cargo check -p uv-resolver for a fast compile check.
3. Run a focused test:

   $ cargo nextest run -p uv -E 'test(test_lock_basic)'

4. If a snapshot changes, review and accept it:

   $ cargo insta test --accept --test-runner nextest -- test_lock_basic

5. Run cargo clippy --workspace --all-targets --all-features --locked -- -D warnings before pushing — uv treats clippy warnings on main as bugs.

Running the full test suite

# Full integration tests (slow; CI runs many shards)
$ cargo nextest run --workspace

# Accept all snapshot diffs
$ cargo insta test --accept --test-runner nextest

Some tests need real Python interpreters at specific versions. Install them with:

$ cargo run python install

The storage directory can be configured with UV_PYTHON_INSTALL_DIR (must be absolute).

A subset of tests requires Git and Git LFS. They can be disabled by turning off the git or git-lfs features.

Writing changes

A few guardrails the maintainers consistently apply, drawn from AGENTS.md:

• Always attempt to add a test case for changed behavior. Prefer integration tests under crates/uv/tests/it/. Prefer insta snapshots over substring assertions, and copy the style of nearby tests.
• Avoid panic!, unreachable!, .unwrap(), unsafe code, and clippy ignores. Prefer patterns like if let and let-chains. Use #[expect(...)] over #[allow(...)] if a clippy rule must be disabled. When unsafe is needed, write a SAFETY: comment.
• Don't shorten variable names. version not ver, requires_python not rp.
• Never run cargo update in bulk. Use cargo update --precise for targeted lockfile changes.
• Use top-level imports rather than local imports or fully qualified names.
• In Rust doc comments, use [TypeName] references so they render as links.

When making Windows-specific changes from a Unix host, run cargo xwin clippy to verify the target compiles.

Cross-referencing the user docs

If you're changing the user surface of a command, its options, or its output format, you also need to:

• Update or add tests in crates/uv/tests/it/ (which often double as the human-readable reference for the command).
• Regenerate the auto-generated reference docs with cargo dev generate-all before previewing the docs locally.
• Edit any narrative pages under docs/ if the change affects guides or concepts.

A separate CI workflow (.github/workflows/check-generated-files.yml) verifies that auto-generated files (CLI reference, JSON schema, etc.) are committed up to date.