# What Is the uv-build Crate in the uv Ecosystem?

> Discover the uv-build crate, a Rust package implementing PEP 517/660 build backend for uv. Learn how it enables Python packaging tools to build wheels and distributions.

- Repository: [Astral/uv](https://github.com/astral-sh/uv)
- Tags: internals
- Published: 2026-03-01

---

**The `uv-build` crate is a lightweight Rust package that implements the PEP 517/660 build backend for the uv ecosystem, exposing a minimal binary that Python packaging tools invoke to build wheels, source distributions, and editable installs.**

The `uv-build` crate serves as the dedicated build backend within the [astral-sh/uv](https://github.com/astral-sh/uv) repository, allowing Python projects to leverage uv's high-performance Rust implementation for package building without depending on the full uv CLI. By isolating the build logic into a tiny (~0.5 MiB) standalone executable, this crate enables downstream projects to use uv's fast, pure-Rust compilation capabilities while maintaining compliance with Python's standardized packaging hooks.

## Architecture and Role of the uv-build Crate

### PEP 517/660 Build Backend Implementation

The `uv-build` crate functions as a **PEP 517/660 compliant build backend**, exposing the standardized entry points that Python packaging tools like `pip` and `build` expect. When a project's [`pyproject.toml`](https://github.com/astral-sh/uv/blob/main/pyproject.toml) declares `uv-build` as its build system, the Python shim in [`crates/uv-build/python/uv_build/__init__.py`](https://github.com/astral-sh/uv/blob/main/crates/uv-build/python/uv_build/__init__.py) translates high-level build requests into subprocess calls to the `uv-build` binary.

### The Binary Bridge Pattern

Rather than embedding Python code that performs builds directly, `uv-build` uses a **binary bridge architecture**. The Python shim ([`uv_build/__init__.py`](https://github.com/astral-sh/uv/blob/main/uv_build/__init__.py)) locates the `uv-build` executable on `PATH`, spawns it with the appropriate sub-command, and captures the artifact path from stdout. This design keeps the Python side minimal while delegating all heavy lifting to Rust code in the companion `uv-build-backend` crate.

## Core Build Operations Supported

The `uv-build` binary implements four primary build operations as defined by PEP 517 and PEP 660:

- **`build-sdist`** – Creates a source distribution (tarball) from the project source
- **`build-wheel`** – Compiles a binary wheel for the target platform
- **`build-editable`** – Produces an editable install (PEP 660) for development workflows
- **`prepare-metadata-for-wheel`** / **`prepare-metadata-for-editable`** – Generates metadata without performing a full build

These operations are invoked via command-line arguments parsed in [`crates/uv-build/src/main.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-build/src/main.rs), which then delegates to corresponding functions in the backend crate such as `uv_build_backend::build_wheel` and `uv_build_backend::build_source_dist`.

## Implementation Flow and Source Structure

### Rust Binary Entry Point

In [`crates/uv-build/src/main.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-build/src/main.rs), the binary initializes logging, parses preview-feature flags, and routes sub-commands to the backend implementation. According to the source code at lines 67–92, the main function matches the incoming command (e.g., `build-wheel`, `build-sdist`) and forwards the request to the appropriate function in `uv-build-backend`, printing the resulting artifact path to stdout.

### Python Shim Layer

The Python-side implementation in [`crates/uv-build/python/uv_build/__init__.py`](https://github.com/astral-sh/uv/blob/main/crates/uv-build/python/uv_build/__init__.py) (lines 37–70) provides the actual PEP 517 hooks. When `pip` calls `build_wheel()`, the shim resolves the binary name (`uv-build` or `uv`), executes it with the proper arguments, and returns the filename captured from stdout as the PEP 517 result.

### Backend Implementation

The actual build algorithms reside in [`crates/uv-build-backend/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-build-backend/src/lib.rs) and its submodules:
- **[`wheel.rs`](https://github.com/astral-sh/uv/blob/main/wheel.rs)** – Wheel creation logic
- **[`source_dist.rs`](https://github.com/astral-sh/uv/blob/main/source_dist.rs)** – Source distribution packaging
- **[`metadata.rs`](https://github.com/astral-sh/uv/blob/main/metadata.rs)** – Metadata extraction and generation

This separation allows `uv-build` to remain a thin wrapper while sharing the same core code that powers the full uv CLI.

## Configuring uv-build in Your Project

To use `uv-build` as your project's build backend, specify it in [`pyproject.toml`](https://github.com/astral-sh/uv/blob/main/pyproject.toml):

```toml
[build-system]
requires = ["uv-build"]
build-backend = "uv_build"

```

When building with `pip`, the tool automatically invokes the uv-build backend:

```bash
$ python -m pip wheel .

# Internally calls uv_build.build_wheel() → spawns `uv-build build-wheel …`

# Output: dist/project-1.0.0-cp311-cp311-manylinux_2_17_x86_64.whl

```

For direct binary invocation (useful in CI/CD scripts):

```bash

# Build a wheel into ./wheelhouse

uv-build build-wheel ./wheelhouse

# Prints: ./wheelhouse/project-1.0.0-py3-none-any.whl

```

Programmatic access via Python:

```python
from uv_build import build_wheel

wheel_path = build_wheel("./wheelhouse")
print("Created wheel:", wheel_path)

```

## Summary

- **`uv-build`** is a minimal Rust crate providing the PEP 517/660 build backend for the uv ecosystem
- It exposes a **tiny binary** (`uv-build`) that Python packaging tools invoke as a subprocess
- The crate acts as a **bridge** between Python build hooks and the Rust implementation in `uv-build-backend`
- It supports **source distributions**, **wheels**, and **editable installs** via standardized commands
- Projects can depend on `uv-build` without pulling in the full uv CLI, keeping dependencies lightweight (~0.5 MiB)

## Frequently Asked Questions

### How does uv-build differ from the main uv CLI?

The `uv-build` crate is a specialized subset of uv's functionality. While the full `uv` CLI provides a complete package manager with resolution, installation, and virtual environment management, `uv-build` only implements the build backend specification. It is designed to be imported as a build-time dependency by other packages, whereas the full CLI is a user-facing tool.

### Why is uv-build packaged as a separate crate?

According to the astral-sh/uv source code, isolating the build backend into its own crate keeps the dependency footprint minimal for projects that need to build from source. By separating the PEP 517 interface (`uv-build`) from the core build algorithms (`uv-build-backend`), the project avoids forcing build dependencies on the full uv toolchain while still delivering uv's performance benefits.

### Does uv-build support editable installs for development?

Yes, `uv-build` fully supports **PEP 660 editable installs** through the `build-editable` command. When a developer runs `pip install -e .` on a project configured with `uv-build`, the Python shim invokes `uv-build build-editable`, which generates a `.pth` file or similar mechanism pointing to the source directory, allowing changes to be reflected immediately without reinstallation.

### How does the Python shim locate the uv-build binary?

The implementation in [`crates/uv-build/python/uv_build/__init__.py`](https://github.com/astral-sh/uv/blob/main/crates/uv-build/python/uv_build/__init__.py) searches for an executable named `uv-build` (or `uv` as a fallback) on the system `PATH`. It resolves the binary location at runtime, spawns it as a subprocess with the build sub-command and output directory arguments, and captures the resulting artifact path from stdout to return to the calling packaging tool.