build

build is the official Python Packaging Authority (PyPA) build frontend: a small, standards-compliant tool that invokes a project’s configured PEP 517 backend (setuptools, hatchling, flit-core, poetry-core, and others) to produce source distributions and wheels. Run as python -m build or the pyproject-build console script, it creates an isolated virtual environment for the build by default, installs the backend’s declared build-time requirements into it, and calls the backend’s hooks to generate artifacts in a dist/ directory.

It is deliberately minimal in scope, deferring all actual build logic to the PEP 517 backend named in a project’s pyproject.toml, and is widely used as the default or recommended build frontend across the Python packaging ecosystem, including in CI pipelines like cibuildwheel (its default builder as of 3.0) and via pipx run build for one-off, dependency-free invocations.

What You Get

• A python -m build / pyproject-build command that builds sdists and wheels using the project’s declared PEP 517 backend
• Isolated build environments by default, with a --no-isolation flag and a pluggable installer (pip or uv via --installer)
• Fine-grained output control (--sdist, --wheel, --metadata) and PEP 517-style config passing (-C, --config-json)
• An importable ProjectBuilder API for programmatic use by other packaging tools, plus first-class integration with cibuildwheel and pipx

Common Use Cases

• Building a Python package’s sdist and wheel locally before uploading to PyPI with twine
• Running package builds in CI pipelines (GitHub Actions, cibuildwheel) as the standard, backend-agnostic build step
• One-off package builds via pipx run build or uvx --from build pyproject-build without polluting the local environment
• Tool authors embedding ProjectBuilder programmatically to build packages as part of a larger packaging or release workflow

Under The Hood

Architecture - The core of the project is src/build/_builder.py, which defines ProjectBuilder, a class that reads a project’s pyproject.toml [build-system] table, resolves and installs the declared backend, and calls PEP 517 hooks (build_sdist, build_wheel, prepare_metadata_for_build_wheel) through the pyproject_hooks dependency. src/build/env.py implements the isolated-environment machinery, src/build/__main__.py provides the CLI entry point, and _exceptions.py/_types.py centralize typed errors and PEP 517 type aliases used throughout.

Tech Stack - Pure Python (100% of the repo), built with flit-core as its own build backend, and depending only on packaging and pyproject_hooks at runtime (plus optional colorama on Windows and an optional uv extra for the faster installer path). It targets Python 3.10+ per current classifiers, with a _compat package handling behavior differences across versions.

Code Quality - The tests/ directory includes unit tests (test_projectbuilder.py, test_env.py, test_util.py) alongside a dedicated test_integration.py and test_self_packaging.py that build real fixture packages under tests/packages/ end-to-end, giving strong confidence that the tool behaves correctly against actual PEP 517 backends rather than only mocks. CI badges for pre-commit, tests, and codecov coverage are all wired into the README, and the project is a mature, actively governed part of the PyPA organization.

API Design - The CLI surface is intentionally narrow and well-documented (a handful of flags covering sdist/wheel selection, isolation, installer choice, and config passing), and the ProjectBuilder class exposes a small, predictable programmatic API for embedding in other packaging tools, consistent with the project’s stated goal of being ‘simple and correct’ rather than feature-rich.