Skip to content
Back to top

# build

A simple, correct Python packaging build frontend.

build reads your project’s pyproject.toml configuration file and invokes build backends to create distribution packages—the files you upload to PyPI or install with pip. It focuses solely on building packages and does not manage dependencies or virtual environments.

## Mission Statement

Many Python tools combine multiple capabilities into one project. For example, pip both installs packages and can build them. While convenient, this tight coupling isn’t always desirable. Some users need standalone build tools for custom environments (outside PyPI), or they manage packages themselves (like Linux distributions do).

This project fills that gap by providing a standalone build tool following modern Python packaging standards for how build tools communicate with backends and how `pyproject.toml` defines build requirements.

We keep dependencies minimal to make build easy to install and use in restricted environments.

## Differences from other tools

Thanks to standardization, all compliant build frontends produce the same outputs (source distributions and wheels) from the same project. The differences are mainly in scope, dependencies, and extra features.

### `uv build`

uv build is essentially equivalent to `python -m build --installer=uv`. Both follow packaging standards. build offers features like `--config-json` for passing complex nested configuration to backends, and the pip installer works on systems that don’t have pre-compiled uv wheels.

### `setup.py sdist bdist_wheel`

build is the modern equivalent of `setup.py sdist bdist_wheel`, supporting any backend — not just setuptools.

### `hatch build`

hatch build is the build command from the Hatch project management tool. It provides a convenient wrapper around the build process as part of the larger Hatch ecosystem for managing Python projects, while build is a standalone tool focused solely on building.

### `flit build`

flit build is the build command from the Flit project. One important difference: flit-core produces slightly different source distributions when built by flit itself compared to other frontends. Using build (or any standards-compliant frontend) ensures consistent outputs regardless of the backend.

### `cibuildwheel`

cibuildwheel is a different kind of tool. While build creates a single wheel for the current platform, cibuildwheel orchestrates building wheels across many platforms and Python versions in CI. It actually calls a build frontend (like build or pip) internally for each platform. Use build to create a pure-Python wheel or a single native wheel; use cibuildwheel when you need to produce native wheels for many platforms.

## Where to start

First time using build? Start with the Getting Started to create your first package.

Need to solve a specific problem? Check the Basic Usage for common workflows, or browse the how-to guides below for your specific scenario.

Looking for technical details? The Command-Line Interface documents all command-line options, and the API Documentation covers the Python API.

Want to understand how it works? Read How it Works to learn about the build process and isolation.