How to contribute

This section describes how to work in the uv codebase. The authoritative source is CONTRIBUTING.md in the repo root; this page summarizes what is most useful when navigating the code.

Picking up work

The Astral team curates two GitHub labels:

• good first issue — appropriate for first-time contributors and rarely require deep uv knowledge.
• help wanted — important issues the team would like to see addressed but cannot prioritize. These vary in difficulty.

Issues labeled bug are also generally good candidates. Issues labeled needs-decision or needs-design are not — please do not open PRs for those.

For new features, the project explicitly asks contributors to discuss first. The maintainers note in CONTRIBUTING.md that they "will almost always close" feature PRs that arrive without prior discussion, since adding a feature creates a long-term maintenance burden.

AI policy

Astral has a written AI policy that applies to all contributions. Contributions that don't follow it are closed.

Contribution flow

1. Open an issue to align on the change (or comment on an existing one).
2. Set up your environment — see Development workflow.
3. Make changes; always attempt to add a test case for changed behavior and prefer integration tests under crates/uv/tests/it/ with insta snapshots.
4. Run linters and tests — see Testing.
5. Open a PR. Releases happen on a regular cadence; routine work merges quickly.

What's in this section

• Development workflow — building, running, and the daily loop.
• Testing — cargo nextest, snapshot tests, Python fixtures, and Git LFS.
• Debugging — logging, common errors, and how to introspect uv's behavior.
• Patterns and conventions — coding style, error handling, resolver patterns.
• Tooling — formatters, linters, generators, and CI infrastructure.