This page documents the distribution of uv as a Python package on PyPI and its internal Python-side logic. While uv is primarily a Rust-based CLI tool, it is also distributed as a Python package to enable seamless integration into existing Python workflows, CI/CD pipelines, and as a dependency for other Python tools.
The uv project provides a Python-side interface and distribution mechanism to ensure that the Rust binary can be easily installed via standard Python tools like pip or pipx pyproject.toml68-83 This distribution includes the uv package itself and a specialized uv-build package used for build backend operations crates/uv-build/Cargo.toml1-4
uv PyPI Package: A wrapper that distributes the compiled Rust binaries for various platforms pyproject.toml5-15find_uv_bin(): A Python utility to locate the uv executable across different installation environments (e.g., standard install, scripts, or development).uv-build: A separate Python distribution for the native PEP 517 build backend crates/uv-build/pyproject.toml1-4maturin pyproject.toml45-51The following diagram illustrates how the Python package relates to the underlying Rust binary and the distribution channels.
Distribution Entity Mapping
Sources: pyproject.toml45-51 crates/uv-build/Cargo.toml1-4
The uv Python package serves as a distribution vehicle for the uv binary. This allows users to run pip install uv and immediately have access to the uv command docs/getting-started/installation.md68-83 The package is built using maturin with the bin binding type, which bundles the Rust executable into the Python wheel pyproject.toml45-49
The package includes internal logic to find the binary path via find_uv_bin(). This function performs an exhaustive search across several locations, including the scripts directory for the current Python environment, platform-specific paths for --prefix installs, and the user scheme directory.
With the release of version 0.12.0, uv init now creates packaged projects using the uv_build backend by default CHANGELOG.md18-38
For details, see uv Python Package.
Sources: pyproject.toml45-51 docs/getting-started/installation.md78-83 CHANGELOG.md18-38
uv provides robust support for Git-based dependencies, allowing users to reference packages directly from Git repositories. This integration involves resolving Git references (branches, tags, SHAs) to specific commits and managing a local cache of Git checkouts.
The implementation includes specialized handling for Git URLs, revision caching, and SHA resolution to ensure reproducible builds even when using moving targets like branches or tags.
For details, see Git Integration.
Git Resolution Components
| Component | Role | Code Entity |
|---|---|---|
uv-git | Crate providing Git repository interaction | crates/uv-git crates/uv/Cargo.toml38 |
uv-git-types | Core types for Git references and sources | crates/uv-git-types crates/uv/Cargo.toml39 |
GitSource | Representation of a Git-based package source | uv_distribution_types::GitSource crates/uv/Cargo.toml33 |
Sources: crates/uv/Cargo.toml33-39
uv is frequently consumed as a dependency in other environments, such as Docker containers and GitHub Actions. The Python package distribution ensures that uv can be listed in requirements.txt or pyproject.toml.
When consumed as a dependency, uv provides:
astral-sh/setup-uv action for automated installation and caching docs/guides/integration/github.md10-31uv-lock, uv-export, and pip-compile docs/guides/integration/pre-commit.md10-49uv pip install --target docs/guides/integration/aws-lambda.md94-119Tools can use uv in Docker by copying the binary from the official image, which avoids needing a Rust toolchain during the build docs/guides/integration/docker.md105-113
Sources: docs/guides/integration/docker.md110-113 docs/guides/integration/aws-lambda.md94-119 docs/guides/integration/docker.md135-139
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.