This document provides a high-level introduction to uv, a Python package and project manager written in Rust. It explains the system's purpose, architecture, key subsystems, and how the codebase is organized. This page serves as an entry point for understanding the entire uv system.
For detailed information on specific subsystems:
uv is an extremely fast Python package and project manager that consolidates the functionality of multiple Python tools into a single binary crates/uv/Cargo.toml1-4 It is written in Rust and designed to be significantly faster than traditional Python packaging tools README.md10-28
pip, pip-tools) README.md26-36poetry, rye) README.md89-125pyenv) README.md188-226pipx) README.md150-186virtualenv) README.md228-230build, twine) README.md123-125Sources: README.md1-45 pyproject.toml5-35 crates/uv/Cargo.toml1-4
uv is organized as a Rust workspace containing multiple crates that implement distinct layers and subsystems crates/uv/Cargo.toml17-69 The architecture follows a layered design with clear separation between user-facing interfaces and low-level services.
For a detailed breakdown of crate boundaries and data flow, see System Architecture.
Sources: crates/uv/Cargo.toml17-69
The uv crate serves as the primary binary entry point crates/uv/Cargo.toml2 It uses the clap crate for parsing command-line arguments and dispatching commands crates/uv/Cargo.toml78
This layered dispatch design cleanly separates CLI parsing from command business logic, improving maintainability.
Sources: crates/uv/Cargo.toml1-118
The workspace crates are specialized for core functions, enabling modular development and clarity.
| Feature | Primary Crate(s) | Purpose |
|---|---|---|
| Command-line interface | uv-cli, uv | CLI parsing, command dispatch |
| Dependency resolution | uv-resolver | PubGrub SAT-solving, universal resolution |
| Package distribution | uv-distribution | Fetching packages, building wheels and sdists |
| Package installation | uv-installer | Generating installation plans, manipulating site-packages |
| Registry communication | uv-client | HTTP clients for PyPI Simple API and JSON API |
| Python interpreter management | uv-python | Discovering Python interpreters, managing installations |
| Virtual environments | uv-virtualenv | Creating isolated virtual environments |
| Cache management | uv-cache | Content-addressed storage, HTTP cache layers |
| Authentication | uv-auth | Credential store, keyring integration, auth helpers |
| Configuration management | uv-settings | Multi-layer settings hierarchy, TOML configuration resolution |
| Workspace/project support | uv-workspace | Cargo-style workspace detection, multi-project metadata export |
| PEP implementations | uv-pep440, uv-pep508 | Versioning, dependency specification parsing |
Sources: crates/uv/Cargo.toml17-69
Sources: crates/uv/Cargo.toml1-118 Cargo.lock220-231
uv unifies and replaces multiple popular Python tools with one fast and comprehensive solution:
uv offers significantly enhanced speed (10-100x faster than pip) and a consistent interface README.md10-28
Sources: README.md26-36 README.md89-125 README.md188-226 README.md150-186 README.md228-230
uv is available through diverse channels to maximize accessibility across platforms and usage scenarios README.md47-81:
The standalone installer supports self-updating the binary crates/uv/Cargo.toml167-169
Sources: README.md47-81 docs/getting-started/installation.md1-150 pyproject.toml1-49
The repository employs a standard Rust workspace organization emphasizing modular crates:
uv/
├── crates/ # Rust workspace members
│ ├── uv/ # Main CLI binary crate
│ ├── uv-resolver/ # Dependency resolution logic
│ ├── uv-python/ # Python interpreter management
│ ├── uv-cli/ # CLI command definitions
│ ├── uv-distribution/ # Package fetching and building
│ ├── uv-installer/ # Installation logic
│ ├── uv-auth/ # Authentication system
│ ├── uv-settings/ # Settings management
│ ├── uv-workspace/ # Workspace detection and metadata
│ └── ... # Other specialized crates
├── docs/ # Documentation sources
├── python/ # Python wrapper and build backend
├── Cargo.lock # Rust lockfile for dependencies
├── pyproject.toml # Python package metadata and build config
└── CHANGELOG.md # Release notes and history
For more on foundational concepts—such as lockfiles, universal resolution, workspaces, and Python version management—see Core Concepts.
Sources: crates/uv/Cargo.toml17-69 pyproject.toml45-50 CHANGELOG.md1-100
This page provides an overview of uv's purpose, architecture, and positioning as a unified Python package and project manager. Detailed design and technical explanations are found in the linked child pages.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.