uv-build-backend

crates/uv-build-backend/ is uv's own PEP 517 build backend, the uv_build Python package. It produces wheels and sdists for pure-Python projects without invoking another build tool. The crate is independent of the rest of uv — it can be used by other tools as a library, and it's published separately as a tiny Python wheel.

Purpose

A focused, fast PEP 517 backend that:

• Reads metadata from pyproject.toml.
• Produces a PEP 660-compatible editable wheel, a regular wheel, or a source distribution.
• Validates filenames, module structure, and project metadata.
• Honors uv-specific extensions like glob-based file inclusion.

Directory layout

crates/uv-build-backend/src/
├── lib.rs              # Re-exports + the top-level Error type
├── metadata.rs         # PyProjectToml parsing, project metadata, validation (~68k chars)
├── settings.rs         # BuildBackendSettings, WheelDataIncludes, ModuleName
├── source_dist.rs      # build_source_dist + list_source_dist
├── wheel.rs            # build_wheel, build_editable, list_wheel, metadata
└── serde_verbatim.rs   # A serde wrapper that preserves original TOML byte spans for diagnostics

Key abstractions

Type	File	Role
PyProjectToml	metadata.rs	The full parsed pyproject.toml. Public API for callers who already have a parsed file.
BuildBackendSettings	settings.rs	uv-specific knobs in [tool.uv.build-backend]: module name, source includes, data includes.
WheelDataIncludes	settings.rs	The PEP 491 data directory layout (purelib, platlib, headers, scripts, data).
ModuleName	settings.rs	Module name with optional dotted submodule path.
ValidationError	metadata.rs	Specific validation failures (missing required field, bad version, …).
build_wheel / build_editable / list_wheel / metadata	wheel.rs	The PEP 517 wheel hooks.
build_source_dist / list_source_dist	source_dist.rs	The PEP 517 sdist hooks.
check_direct_build	metadata.rs	Helper used by tests / cargo dev to verify a tree builds correctly.

How it works

For a wheel:

1. Parse pyproject.toml into PyProjectToml. Validate that all required fields are present and have the right shape (metadata.rs::ValidationError).
2. Walk the source tree using a portable glob filter (crates/uv-globfilter/) plus the includes/excludes from [tool.uv.build-backend]. Apply the standard exclusions (.git, __pycache__, …) and the uv-specific bans on virtualenvs and external symlinks.
3. Pack the files into a zip with the right header layout (crates/uv-build-backend/src/wheel.rs).
4. Compute SHA-256 hashes per file and write the RECORD file at the end.
5. Write WHEEL, METADATA, and entry_points.txt files.

For an sdist:

1. Parse pyproject.toml.
2. Walk the source tree, applying the source-dist-specific includes (which by default include anything required for a successful build, including pyproject.toml itself).
3. Tar the files into a .tar.gz archive at the requested output path.
4. Validate that pyproject.toml is included (a hard error per PEP 517).

Integration points

• The crate has no runtime dependency on the rest of uv. It depends on uv-globfilter, uv-pep440, uv-pep508, uv-pypi-types, uv-normalize, uv-fs, and uv-warnings, but not on the resolver, installer, or HTTP client.
• The Python distribution shell lives in crates/uv-build/ (and is what gets uploaded as the uv_build PyPI package).
• The dev wrapper command uv build-backend (from crates/uv/src/commands/build_backend.rs) invokes these hooks directly for testing.

Entry points for modification

• A new metadata field — metadata.rs::PyProjectToml and validate.
• A new include/exclude rule — settings.rs::BuildBackendSettings. Glob support is via uv-globfilter.
• Output customization — wheel.rs and source_dist.rs are short and self-contained.

Key source files

File	Purpose
crates/uv-build-backend/src/metadata.rs	Project-metadata model and validation.
crates/uv-build-backend/src/wheel.rs	Wheel build / list / metadata hooks.
crates/uv-build-backend/src/source_dist.rs	Sdist build / list hooks.
crates/uv-build-backend/src/settings.rs	uv-specific build-backend settings.

See also

• uv-build-frontend — the frontend that calls this (and other) backends.
• uv-globfilter — for the include/exclude glob engine.
• uv-build — the Python distribution shell.