# Contributor handoff — astral-sh/uv

> Canonical page: https://codevetter.com/unpack/uv/agent-handoff

# Contributor handoff — astral-sh/uv

Scanned commit a9e231a7e377342084d1c0b6009409bdec41acc5 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Read AGENTS.md and CONTRIBUTING.md before editing. Prefer a narrow cargo nextest filter and insta snapshots over new unit tests or the full suite. Do not use the release profile unless asked. The Rust library is an unsupported entrypoint; behavior changes belong in the CLI and the command modules. Preview-gated behavior, generated docs, and the lockfile schema are the traps that most often produce a correct-looking diff that fails review. Security-sensitive edits should be checked against agents/references/threat-model.md, and privileged GitHub workflows must go through the automation dispatcher rather than pull_request_target.
- AGENTS.md requires matching existing test style, checking for an existing test, preferring it/ integration tests, preferring insta snapshots, avoiding panic, unreachable, unwrap, and unsafe, preferring exhaustive matches, using #[expect] over allow, and using cargo update --precise for lockfile bumps. Do not add pull_request_target workflows; use .github/automations-dispatch.json. Do not leak conversation history into comments or PR text. — [AGENTS.md#L1-L32](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/AGENTS.md#L1-L32)
- First files for a command change are crates/uv-cli/src/lib.rs (the clap type), the matching arm in crates/uv/src/lib.rs, the command module under crates/uv/src/commands/, and a nearby test under crates/uv/tests. For resolver or lockfile work also read crates/uv-resolver/src/resolver/mod.rs and crates/uv-lock/src/lock/mod.rs. — [crates/uv-cli/src/lib.rs#L451-L460](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-cli/src/lib.rs#L451-L460) [crates/uv/src/lib.rs#L638-L640](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/lib.rs#L638-L640) [crates/uv/src/commands/mod.rs#L83-L105](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/commands/mod.rs#L83-L105)
- Run the smallest test. The documented form is cargo nextest run -E 'test(test_name)'. Snapshot review is cargo insta test --accept --test-runner nextest -- <test_name> or cargo insta review. Do not cargo build --release. Development builds omit git metadata unless UV_INTERNAL__BUILD_GIT_INFO=1. — [CONTRIBUTING.md#L63-L150](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/CONTRIBUTING.md#L63-L150) [AGENTS.md#L6-L8](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/AGENTS.md#L6-L8)
- uv::main's own docs say the Rust entrypoint is not the public API and is unsafe to call once other threads are running. Changes that only affect library callers will not be supported. Behavior should stay reachable from the uv binary. — [crates/uv/src/lib.rs#L3006-L3020](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/lib.rs#L3006-L3020)
- A new setting must be combined in uv-settings and will be ignored in the wrong file: project fields are rejected in uv.toml, and a uv.toml next to pyproject.toml causes overlapping [tool.uv] fields to be ignored. Tool and self commands do not read project config at all. — [crates/uv/src/lib.rs#L312-L328](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/lib.rs#L312-L328) [docs/concepts/configuration-files.md#L8-L16](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/docs/concepts/configuration-files.md#L8-L16)
- Preview features are not silently on. New behavior that should be experimental belongs in the PreviewFeature enum and should warn with the same 'experimental and may change' pattern used by --output-format json and --default. Turning it on by default is a behavior change for every UV_PREVIEW user. — [crates/uv-preview/src/lib.rs#L231-L251](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-preview/src/lib.rs#L231-L251) [crates/uv/src/commands/project/sync.rs#L97-L101](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/commands/project/sync.rs#L97-L101) [crates/uv/src/commands/python/install.rs#L337-L341](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/commands/python/install.rs#L337-L341)
- After changing CLI help, settings, env vars, preview flags, or the uv.toml schema, regenerate with the uv-dev commands (generate-cli-reference, generate-options-reference, generate-env-vars-reference, generate-preview-features-reference, generate-json-schema) or generate-all. CI job check-generated-files compares them. — [crates/uv-dev/src/lib.rs#L56-L69](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-dev/src/lib.rs#L56-L69) [.github/workflows/ci.yml#L85-L91](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/.github/workflows/ci.yml#L85-L91)
- Lockfile version is a single supported major, currently 1. Adding a field that old readers cannot skip is a format break. Prefer a revision-compatible addition. LockfileFormatCheck and LockWithoutMetadata are preview flags that change how --locked and --check compare bytes. — [crates/uv-lock/src/lock/mod.rs#L88-L104](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-lock/src/lock/mod.rs#L88-L104) [crates/uv-lock/src/lock/mod.rs#L293-L305](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-lock/src/lock/mod.rs#L293-L305) [crates/uv-preview/src/lib.rs#L326-L329](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-preview/src/lib.rs#L326-L329)
- Cache directory names are versioned. Bumping CacheBucket::to_str without updating the tests named in the comments (cache_prune.rs, cache_clean.rs, lock.rs) and without a migration story will make existing user caches look empty and will fail CI snapshots. — [crates/uv-cache/src/lib.rs#L1298-L1326](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv-cache/src/lib.rs#L1298-L1326)
- Windows-only code paths include uvw, the registry Python search, test-windows-registry, and trampoline tests. AGENTS.md says to use cargo xwin clippy when changing Windows behavior from Unix. The uvw binary is behind the windows-gui-bin feature and is not in the default build. — [AGENTS.md#L7](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/AGENTS.md#L7) [crates/uv/Cargo.toml#L212-L234](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/Cargo.toml#L212-L234) [crates/uv/src/bin/uvw.rs#L1-L2](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/crates/uv/src/bin/uvw.rs#L1-L2)
- Do not suppress the dangerous-triggers lint or add privileged pull_request_target workflows. Security review is a separate CI job (pull-request-security-review.yml) when plan.yml sets review-security. Read agents/references/threat-model.md before changing auth, hashing, Git pinning, archive extraction, or publish. — [AGENTS.md#L20-L23](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/AGENTS.md#L20-L23) [.github/workflows/ci.yml#L29-L38](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/.github/workflows/ci.yml#L29-L38) [agents/references/threat-model.md#L1-L15](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/agents/references/threat-model.md#L1-L15)
- Formatting is cargo fmt --all for Rust, ruff format via uv run --only-group=check for Python, and prettier 3.9.0 for Markdown and YAML. Clippy is cargo clippy --workspace --all-targets --all-features --locked -- -D warnings. jq is required to validate pyproject.toml against the checked-in schema. — [CONTRIBUTING.md#L152-L176](https://github.com/astral-sh/uv/blob/a9e231a7e377342084d1c0b6009409bdec41acc5/CONTRIBUTING.md#L152-L176)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)