The uv build backend is a native PEP 517 compliant system designed to transform Python source trees into standard distribution formats (wheels and source distributions). While uv supports any PEP 517 backend (e.g., hatchling, setuptools), it provides its own optimized backend, uv-build-backend, which is specialized for pure-Python projects.
The backend is implemented in Rust and exposed as the uv_build Python package. It handles metadata validation, file discovery based on glob patterns, and the generation of .whl and .tar.gz archives crates/uv-build-backend/src/lib.rs99-121
Key characteristics include:
async-zip implementation with buffering strategies for efficiency, specifically using a 16 MiB limit (WHOLE_FILE_ZIP_ENTRY_LIMIT) for fast-path writes crates/uv-build-backend/src/wheel.rs32-40src layout (module_root) and automatic module name derivation from the package name crates/uv-build-backend/src/settings.rs15-49pyproject.toml against PEP specifications and prevents common mistakes like including virtual environments in distributions crates/uv-build-backend/src/metadata.rs52-116 crates/uv-build-backend/src/lib.rs83-840.9.30 and 0.10.12 crates/uv-build-backend/src/metadata.rs36-37The build backend logic is encapsulated in the uv-build-backend crate. It provides a core library used by the uv CLI and the standalone uv_build Python package crates/uv-build-backend/src/lib.rs1-13
The following diagram maps high-level build concepts to the specific Rust modules and functions that implement them within uv-build-backend.
Sources: crates/uv-build-backend/src/lib.rs8-13 crates/uv-build-backend/src/wheel.rs43-91 crates/uv-build-backend/src/source_dist.rs30-56 crates/uv-build-backend/src/metadata.rs52-116 crates/uv-build-backend/src/lib.rs107-121 crates/uv-build-backend/src/lib.rs158-188
When a build is initiated, the backend follows a pipeline to resolve metadata and package files.
| Stage | Responsibility | Primary Entity |
|---|---|---|
| Parsing | Reads and validates pyproject.toml | PyProjectToml::parse crates/uv-build-backend/src/metadata.rs1-25 |
| Discovery | Finds Python modules and data files | find_roots crates/uv-build-backend/src/wheel.rs144-152 |
| Filtering | Applies PEP 639 glob patterns for inclusion/exclusion | GlobDirFilter crates/uv-globfilter/src/glob_dir_filter.rs15-18 |
| Archiving | Writes files to Zip (wheel) or TarGz (sdist) | DirectoryWriter crates/uv-build-backend/src/lib.rs107-121 |
The backend implements the standard hooks required by PEP 517/660. Within the uv codebase, these hooks are handled by a dedicated command module in crates/uv/src/commands/build_backend.rs that bridges the CLI to the backend library.
This diagram shows how the standard Python build hooks are dispatched to the Rust implementation via the uv command handlers.
Sources: crates/uv/src/commands/build_backend.rs8-91 crates/uv-build-backend/src/lib.rs8-13
For deeper technical implementation details, refer to the following child pages:
uv-build-backend crate internals, including the DirectoryWriter trait crates/uv-build-backend/src/lib.rs107-121 BuildBackendSettings for tool.uv.build-backend configuration crates/uv-build-backend/src/settings.rs15-174 metadata validation logic crates/uv-build-backend/src/metadata.rs52-116 and the specific implementation of wheel and sdist creation.uv-build-frontend crate, how uv invokes external build backends (like setuptools or hatchling), and the BuildDispatch mechanism used for build isolation and environment preparation.Sources: