uv-build: The uv build backend

0.11.2 verified Tue May 12 auth: no python install: stale

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.

pip install uv-build

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.

gotcha Attempting to execute shell commands directly as Python code will result in a `SyntaxError`. ↓

fix Ensure that any shell commands are executed in a shell environment (e.g., using `subprocess` module in Python, or by running directly in a terminal), and that `.py` files contain valid Python syntax.

gotcha The test script encountered a Python `SyntaxError` by attempting to run a shell command (`mkdir`) directly as Python code, preventing the proper execution of `uv` commands. ↓

fix Ensure Python scripts only contain valid Python syntax. For executing shell commands, use Python's `subprocess` module (e.g., `subprocess.run(['mkdir', 'my_python_project'])`) or `os.system`.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 18.1M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.8s - 19M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 19.9M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.7s - 20M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 11.8M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.5s - 12M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 11.5M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.7s - 12M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 17.6M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 2.1s - 18M

3.9 slim (glibc) - - - -

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 last tested: 2026-04-24

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/