Uv Build

uv-build: Python Build Backend

uv_build is Astral's Rust-based build backend for Python packages. As of uv-build 0.11.11 (May 2026), it is the native backend documented by uv for most pure Python packages. Pure Python packages only: no C/Rust extensions.

When to Use uv-build

Is your package pure Python?
├─ YES → Needs VCS versioning, build hooks, or dynamic metadata?
│  ├─ NO  → uv_build (fast, zero-config, excellent defaults)
│  └─ YES → hatchling (extensible, plugin ecosystem)
└─ NO  → What kind of extensions?
   ├─ Rust (PyO3)     → maturin
   ├─ C/C++ (CMake)   → scikit-build-core
   └─ C/C++ (classic) → setuptools

Migration blocker: dynamic = [...] is not supported. Projects using dynamic = ["version"] with hatchling/setuptools must switch to static versions in pyproject.toml (use uv version --bump for version management).

Setup

[build-system]
requires = ["uv_build>=0.11.7,/__init__.py` (src layout).

```toml
[tool.uv.build-backend]
module-root = "src"          # Default (src layout)
module-root = ""             # Flat layout (package at project root)
module-name = "my_package"   # Override auto-detected name

Multiple Modules

[tool.uv.build-backend]
module-name = ["foo", "bar"]

Namespace Packages (PEP 420)

[tool.uv.build-backend]
module-name = "cloud.database"    # Dotted name — parent must NOT have __init__.py

For multiple namespace roots:

[tool.uv.build-backend]
namespace = true
module-name = ["cloud.database", "cloud.auth"]

Type Stub Packages

Auto-detected from -stubs suffix in package name. Uses __init__.pyi instead of __init__.py.

File Inclusion/Exclusion

[tool.uv.build-backend]
source-include = ["tests/**", "CHANGELOG.md"]    # Extra files for sdist
source-exclude = ["*.bin", "benchmarks/**"]       # Exclude from sdist AND wheel
wheel-exclude = ["tests/**"]                      # Exclude from wheel only
default-excludes = true                           # __pycache__, *.pyc (default on)

Patterns: PEP 639 portable glob syntax. Exclusions always override inclusions.

Safety features:

• Warns on 10k+ files (likely traversing .venv or node_modules)
• Detects virtual environments and skips them
• pyproject.toml + module source always included regardless of patterns

Preview Included Files

uv build --list       # Show what would be included (no actual build)

Wheel Data Directories

[tool.uv.build-backend.data]
scripts = "bin"              # -> /bin (executables)
headers = "include/mylib"    # -> include dir (C headers)
data = "share"               # -> venv root (careful: can overwrite!)

Build Commands

uv build                          # Build sdist + wheel to dist/
uv build --sdist                  # Source distribution only
uv build --wheel                  # Wheel only
uv build --list                   # Preview included files
uv build --no-sources             # Test PyPI compatibility (strips tool.uv.sources)
uv build --package          # Specific workspace member
uv build --build-constraints c.txt # Pin build dependency versions
uv build --require-hashes         # Hash verification for build deps
uv build --force-pep517           # Bypass fast path

Publishing Workflow

uv version                        # Check current
uv version --bump minor           # 1.0.0 -> 1.1.0
uv version --bump patch --dry-run # Preview
uv build                          # Build
uv publish                        # Upload to PyPI
uv publish --check-url https://pypi.org/simple/  # Skip if already published

Prevent Accidental Publication

[project]
classifiers = ["Private :: Do Not Upload"]

Editable Installs

uv_build uses static .pth files for editable installs (not dynamic import hooks like setuptools). This works correctly with type checkers and IDEs out of the box, no editable_mode = "compat" workaround needed.

uv sync                  # Installs project as editable by default
uv pip install -e .      # Explicit editable install

Metadata Validation

uv_build is strict about metadata:

• Rejects project.description with newlines
• Enforces SPDX license expressions
• Validates classifiers
• Rejects non-UTF-8 READMEs
• Blocks reserved entrypoint groups (must use project.scripts/project.gui-scripts)

No dynamic metadata: dynamic = [...] is not supported. All metadata must be static in pyproject.toml.

Complete Example

[project]
name = "cloud-database"
version = "2.1.0"
description = "Cloud database toolkit"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
dependencies = ["sqlalchemy>=2.0"]

[project.scripts]
cloud-db = "cloud_database.cli:main"

[build-system]
requires = ["uv_build>=0.11.7,=61.0"]
build-backend = "setuptools.build_meta"

# AFTER
[build-system]
requires = ["uv_build>=0.11.7,=0.11.7,=3.4"]
build-backend = "flit_core.buildapi"

# AFTER  (flit uses flat layout by default)
[build-system]
requires = ["uv_build>=0.11.7,<0.12"]
build-backend = "uv_build"

[tool.uv.build-backend]
module-root = ""

Verification

uv build --list          # Check included files match expectations
uv build                 # Build and inspect artifacts
uv build --no-sources    # Verify PyPI compatibility

Limitations

| Limitation | Impact | Alternative | | --------------------- | -------------------------------------- | --------------------------------------------- | | Pure Python only | No C/C++/Cython/Rust extensions | setuptools, maturin, scikit-build-core | | No dynamic metadata | Can't derive version from VCS/git tags | hatchling + hatch-vcs, or uv version --bump | | No build hooks | No code gen, protobuf, asset bundling | hatchling with build hooks | | No setup.py/setup.cfg | Must fully convert to pyproject.toml | Convert first, then migrate | | Upper-bound pinning | Must update requires when upgrading | Manageable with uv version workflow |

Anti-Patterns

| Anti-Pattern | Fix | | --------------------------------------------- | ------------------------------------------------------- | | Using uv_build for packages with C extensions | Use setuptools, maturin, or scikit-build-core | | Unbounded backend in CI/published packages | Use a tested minor range and bump deliberately | | source-include = ["**/*"] | Let defaults handle it; add specific patterns only | | Forgetting --no-sources test before publish | Sources are dev-only; verify PyPI-only resolution works | | Dynamic version from __init__.py | Static version in pyproject.toml + uv version --bump |

What This Skill is NOT

• Not for building C/Rust/Cython extensions
• Not for projects requiring VCS-derived versioning
• Not for complex build pipelines needing hooks
• Not a uv project management guide (see uv skill)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hyperb1iss
• Source: hyperb1iss/hyperskills
• License: MIT
• Homepage: https://hyperbliss.tech

Install and usage instructions live in the source repository linked above.