uv-build: The uv build backend

0.11.2 · active · verified Sun Mar 29

uv-build is the official PEP 517 build backend for uv, the fast Python package and project manager. It enables uv to efficiently create source distributions and binary wheels for Python projects. The package is a slimmed-down version of uv itself, containing only the necessary components for the build backend functionality. It is under active development with frequent releases, often multiple times a week, ensuring tight integration and performance with the main uv tool.

Warnings

breaking Version 0.11.0 included significant changes to uv's networking stack (driven by a `reqwest` upgrade to v0.13), which may rarely result in previously trusted SSL/TLS certificates being rejected. Exercise caution when upgrading in environments sensitive to network configurations.
Fix: Ensure your environment's certificate stores are up-to-date, or investigate specific certificate issues if network requests begin failing.
gotcha The `uv-build` backend currently only supports pure Python code. If your project includes extension modules (e.g., written in C, C++, Rust), or requires a more flexible project layout with custom build scripts, you will need to use an alternative build backend like `hatchling` or `setuptools`.
Fix: For projects with non-pure Python components, configure your `pyproject.toml` to use a different build backend (e.g., `hatchling.build_api` or `setuptools.build_meta`).
gotcha When publishing packages, it is recommended to run `uv build --no-sources`. This ensures that the package builds correctly even when `tool.uv.sources` (custom dependency sources for development) are disabled, as is common with other build tools or in CI/CD environments.
Fix: Always use `uv build --no-sources` before publishing your package to a public index to verify build integrity without local source overrides.
gotcha The `uv.lock` file, which pins exact dependency versions for reproducibility, should always be committed to version control and should *not* be manually edited. uv automatically manages this file.
Fix: Treat `uv.lock` as a machine-generated file. Use `uv` CLI commands (`uv add`, `uv remove`, `uv lock --upgrade-package`) to manage dependencies, which will automatically update the lockfile.

Install

pip install uv-build Install uv-build

Imports

uv-build as a backend

uv-build is a PEP 517 build backend and is not typically imported directly in user-facing Python code. It is invoked implicitly by build frontends like the `uv build` command or other packaging tools configured in `pyproject.toml`.

uv-build functions as a backend, not a library meant for direct programmatic imports by end-users. Its interaction is through the PEP 517 build system interface.

Quickstart

To use `uv-build`, you typically configure it in your `pyproject.toml` file under the `[build-system]` section. This tells build tools like `uv` how to build your project. After configuration, you use the `uv build` command to create your package distributions. The example demonstrates setting up a basic project and explicitly configuring `uv-build` as the backend.

mkdir my_python_project
cd my_python_project

# Initialize a uv project (this creates pyproject.toml)
uv init

# Edit pyproject.toml to specify uv-build as the build backend
# This content should be placed in pyproject.toml
# --- pyproject.toml ---
# [project]
# name = "my-package"
# version = "0.1.0"
# dependencies = []
#
# [build-system]
# requires = ["uv-build>=0.11.2"]
# build-backend = "uv_build"
# ---

# Build your package (creates sdist and wheel in ./dist)
uv build

# Optionally, publish to a registry (e.g., TestPyPI)
# uv publish --token $UV_PUBLISH_TOKEN --publish-url https://test.pypi.org/legacy/

view raw JSON →