Scroll to navigation

BUILD(1) build BUILD(1)

NAME

build - build 1.2.2

A simple, correct Python packaging build frontend.

build manages pyproject.toml-based builds, invoking build-backend hooks as appropriate to build a distribution package. It is a simple build tool and does not perform any dependency management.

PYTHON -M BUILD


A simple, correct Python build frontend.


By default, a source distribution (sdist) is built from {srcdir}
and a binary distribution (wheel) is built from the sdist.
This is recommended as it will ensure the sdist can be used
to build wheels.


Pass -s/--sdist and/or -w/--wheel to build a specific distribution.
If you do this, the default behavior will be disabled, and all
artifacts will be built from {srcdir} (even if you combine
-w/--wheel with -s/--sdist, the wheel will be built from {srcdir}).

python -m build [-h] [--version] [--verbose] [--sdist] [--wheel] [--outdir PATH]


                [--skip-dependency-check] [--no-isolation | --installer {pip,uv}]


                [--config-setting KEY[=VALUE]]


                [srcdir]


python -m build positional arguments

•
srcdir - source directory (defaults to current directory)

python -m build options

  • -h, --help - show this help message and exit
  • --version, -V - show program's version number and exit
  • --verbose, -v - increase verbosity (default: 0)
  • --sdist, -s - build a source distribution (disables the default behavior)
  • --wheel, -w - build a wheel (disables the default behavior)
  • --outdir PATH, -o PATH - output directory (defaults to {srcdir}/dist)
  • --skip-dependency-check, -x - do not check that build dependencies are installed
  • --no-isolation, -n - disable building the project in an isolated virtual environment. Build dependencies must be installed separately when this option is used
  • --installer INSTALLER - Python package installer to use (defaults to pip)
  • --config-setting KEY[=VALUE], -C KEY[=VALUE] - settings to pass to the backend. Multiple settings can be provided. Settings beginning with a hyphen will erroneously be interpreted as options to build if separated by a space character; use --config-setting=--my-setting -C--my-other-setting (default: None)

Note:

A pyproject-build CLI script is also available, so that tools such as pipx <https://github.com/pipxproject/pipx> can use it.


By default build will build the package in an isolated environment, but this behavior can be disabled with --no-isolation.

MISSION STATEMENT

In the Python ecosystem, the build system tools and the package management are very intertwined. While it might be useful for user to be able to access all this capabilities in a single project (such as pip <https://github.com/pypa/pip>), there are several use cases where this is not desirable. The main being custom environments (outside PyPI <https://pypi.org/>) or situations where the user does its own package management, such as Linux distributions.

This project aims to fit the "building packages hole" for such use-cases in PEP 517 <https://peps.python.org/pep-0517/>/PEP 518 <https://peps.python.org/pep-0518/> workflows.

As it is intended to be used by users that do their own package management, we will try to keep dependencies to a minimum, in order to try make bootstrapping easier.

DIFFERENCES FROM OTHER TOOLS

pep517.build

build implements a CLI tailored to end users.

pep517.build contained a proof-of-concept of a PEP 517 <https://peps.python.org/pep-0517/> frontend. It "implement[ed] essentially the simplest possible frontend tool, to exercise and illustrate how the core functionality can be used". It has since been deprecated and is scheduled for removal <https://github.com/pypa/pep517/pull/83>.

setup.py sdist bdist_wheel

build is roughly the equivalent of setup.py sdist bdist_wheel but with PEP 517 <https://peps.python.org/pep-0517/> support, allowing use with projects that don't use setuptools.

Custom Behaviors

Fallback Backend

As recommended in PEP 517 <https://peps.python.org/pep-0517/>, if no backend is specified, build will fallback to setuptools.build_meta:__legacy__.

INSTALLATION

build can be installed via pip <https://github.com/pypa/pip> or an equivalent:

$ pip install build


You can also check out the latest git tag <https://github.com/pypa/build/tags>, download a tarball <https://github.com/pypa/build/releases> from GitHub, or manually fetch the artifacts from the project page <https://pypi.org/project/build/> on PyPI. Attestations <https://github.com/pypa/build/attestations> are available after 1.2.1 and can be verified with the gh CLI tool:

$ python -m pip --no-cache-dir download --no-deps build
$ gh attestation verify build*.whl --repo pypa/build


Build plans to support PEP 740 <https://peps.python.org/pep-0740> if accepted.

Tip:

If you prefer, or are already using virtualenv <https://virtualenv.pypa.io> in your workflow, you can install build with the optional virtualenv dependency: 

$ pip install 'build[virtualenv]'


this way, build will use virtualenv <https://virtualenv.pypa.io> for isolation, instead of venv <https://docs.python.org/3/library/venv.html>. This can be particularly useful, for example, when using automation tools that rely on virtualenv <https://virtualenv.pypa.io>, such as tox <https://tox.readthedocs.org/>, or when your operating system's Python package does not include venv <https://docs.python.org/3/library/venv.html> in the standard installation (such as some versions of Ubuntu).

There is also a uv extra, which can be used for --installer=uv if you don't have another install of uv available.



Bootstrapping

This package can build itself only with the tomli (can be omitted in Python 3.11+) and pyproject-hooks dependencies. The --skip-dependency-check flag should be used in this case.

Compatibility

build is verified to be compatible with the following Python versions:

  • 3.8
  • 3.9
  • 3.10
  • 3.11
  • 3.12
  • PyPy3

CHANGELOG

1.2.2 (2024-09-06)


1.2.1 (2024-03-28)

•
Avoid error when terminal width is undetectable on Python < 3.11 (PR #761 <https://github.com/pypa/build/pull/761>)

1.2.0 (2024-03-27)


1.1.1 (2024-02-29)


1.1.0 (2024-02-29)


1.0.3 (2023-09-06)

•
Avoid CPython 3.8.17, 3.9.17, 3.10.12, and 3.11.4 tarfile symlink bug triggered by adding data_filter in 1.0.0. (PR #675 <https://github.com/pypa/build/pull/675>, fixes issue #674 <https://github.com/pypa/build/issues/674>)

1.0.0 (2023-09-01)


0.10.0 (2023-01-11)


0.9.0 (2022-10-27)


0.8.0 (2022-05-22)


Breaking Changes

•
Failure to create a virtual environment in the build.env module now raises build.FailedProcessError (PR #442 <https://github.com/pypa/build/pull/442>)

0.7.0 (2021-09-16)

•
Add build.util module with an high-level utility API (PR #340 <https://github.com/pypa/build/pull/340>)

0.6.0.post1 (2021-08-05)

•
Fix compatibility with Python 3.6 and 3.7 (PR #339 <https://github.com/pypa/build/pull/339>, Fixes #338 <https://github.com/pypa/build/issues/338>)

0.6.0 (2021-08-02)


Breaking Changes

•
Dropped support for Python 2 and 3.5.

0.5.1 (2021-06-22)


0.5.0 (2021-06-19)


Breaking Changes


0.4.0 (2021-05-23)


Breaking Changes


0.3.1 (2021-03-09)


0.3.0 (2021-02-19)


0.2.1 (2021-02-09)

•
Fix error from unrecognised pip flag on Python 3.6.0 to 3.6.5 (PR #227 <https://github.com/pypa/build/pull/227>, Fixes #226 <https://github.com/pypa/build/issues/226>)

0.2.0 (2021-02-07)


Breaking changes

•
Move config_settings argument to the hook calls (PR #218 <https://github.com/pypa/build/pull/218>, Fixes #216 <https://github.com/pypa/build/issues/216>)

0.1.0 (2020-10-29)

  • Moved the upstream to PyPA
  • Fixed building with isolation in a virtual environment
  • Added env.IsolatedEnv abstract class
  • Added env.IsolatedEnvBuilder (replaces env.IsolatedEnvironment usages)
  • Added python_executable argument to the ProjectBuilder constructor
  • Added --version/-V option to the CLI
  • Added support for Python 3.9
  • Added py.typed marker
  • Various miscellaneous fixes in the virtual environment creation
  • Many general improvements in the documentation
  • Documentation moved to the furo theme
  • Updated the CoC to the PSF CoC, which PyPA has adopted

Breaking changes

  • Renamed the entrypoint script to pyproject-build
  • Removed default arguments from all paths in ProjectBuilder
  • Removed ProjectBuilder.hook
  • Renamed __main__.build to __main__.build_package
  • Changed the default outdir value to {srcdir}/dest
  • Removed env.IsolatedEnvironment

0.0.4 (2020-09-08)

  • Packages are now built in isolation by default
  • Added --no-isolation/-n flag to build in the current environment
  • Add --config-setting/-C option to pass options to the backend
  • Add IsolatedEnvironment class
  • Fix creating the output directory if it doesn't exit
  • Fix building with in-tree backends
  • Fix broken entrypoint script (python-build)
  • Add warning about incomplete verification when verifying extras
  • Automatically detect typos in the build system table
  • Minor documentation improvements

0.0.3.1 (2020-06-10)

  • Fix bug preventing the CLI from being invoked
  • Improved documentation

0.0.3 (2020-06-09)

  • Misc improvements
  • Added documentation

0.0.2 (2020-05-29)

  • Add setuptools as a default fallback backend
  • Fix extras handling in requirement strings

0.0.1 (2020-05-17)

•
Initial release

API DOCUMENTATION

build module

build - A simple, correct Python build frontend

Bases: Exception

Exception raised when a backend operation fails.


Bases: Exception

Exception raised by build.ProjectBuilder.


Bases: BuildException

Exception raised when the [build-system] table in pyproject.toml is invalid.


Bases: Exception

Exception raised when a setup or preparation operation fails.


Bases: object

The PEP 517 consumer API.

  • source_dir (str | PathLike[str]) -- The source directory
  • python_executable (str) -- The python executable where the backend lives
  • runner (Callable[[Sequence[str], str | None, Mapping[str, str] | None], None]) -- Runner for backend subprocesses


The runner, if provided, must accept the following arguments:

  • cmd: a list of strings representing the command and arguments to execute, as would be passed to e.g. 'subprocess.check_call'.
  • cwd: a string representing the working directory that must be used for the subprocess. Corresponds to the provided source_dir.
  • extra_environ: a dict mapping environment variable names to values which must be set for the subprocess execution.

The default runner simply calls the backend hooks in a subprocess, writing backend output to stdout/stderr.

Build a distribution.
  • distribution (Literal['sdist', 'wheel', 'editable']) -- Distribution to build (sdist or wheel)
  • output_directory (str | PathLike[str]) -- Directory to put the built distribution in
  • config_settings (Mapping[str, str | Sequence[str]] | None) -- Config settings for the build backend
  • metadata_directory (str | None) -- If provided, should be the return value of a previous prepare call on the same distribution kind

str
The full path to the built distribution


The dependencies defined in the pyproject.toml's build-system.requires field or the default build dependencies if pyproject.toml is missing or build-system is undefined.

Return the dependencies which are not satisfied from the combined set of build_system_requires and get_requires_for_build() for a given distribution.
  • distribution (Literal['sdist', 'wheel', 'editable']) -- Distribution to check (sdist or wheel)
  • config_settings (Mapping[str, str | Sequence[str]] | None) -- Config settings for the build backend

set[tuple[str, ...]]
Set of variable-length unmet dependency tuples


TypeVar(_TProjectBuilder, bound= ProjectBuilder)


Return the dependencies defined by the backend in addition to build_system_requires for a given distribution.
  • distribution (Literal['sdist', 'wheel', 'editable']) -- Distribution to get the dependencies of (sdist or wheel)
  • config_settings (Mapping[str, str | Sequence[str]] | None) -- Config settings for the build backend

set[str]


Generate the metadata directory of a distribution and return its path.

If the backend does not support the prepare_metadata_for_build_wheel hook, a wheel will be built and the metadata will be extracted from it.

output_directory (str | PathLike[str]) -- Directory to put the metadata distribution in
str
The path of the metadata directory


Prepare metadata for a distribution.
  • distribution (Literal['sdist', 'wheel', 'editable']) -- Distribution to build (must be wheel)
  • output_directory (str | PathLike[str]) -- Directory to put the prepared metadata in
  • config_settings (Mapping[str, str | Sequence[str]] | None) -- Config settings for the build backend

str | None
The full path to the prepared metadata directory


The Python executable used to invoke the backend.

Project source directory.


Bases: Warning

Warning raised when a possible typo is found.


Verify that a dependency and all of its dependencies are met.
  • req_string (str) -- Requirement string
  • parent_extras (Set[str]) -- Extras (eg. "test" in myproject[test])

Unmet dependencies
Iterator[tuple[str, ...]]


build.env module

Bases: IsolatedEnv

Isolated environment which supports several different underlying implementations.

Install packages from PEP 508 requirements in the isolated build environment.
requirements (Collection[str]) -- PEP 508 requirement specification to install
Passing non-PEP 508 strings will result in undefined behavior, you should not rely on it. It is merely an implementation detail, it may change any time without warning.
None


Generate additional env vars specific to the isolated environment.
dict[str, str]


The location of the isolated build environment.

The python executable of the isolated build environment.


Bases: Protocol

Isolated build environment ABC.

Generate additional env vars specific to the isolated environment.
Mapping[str, str] | None


The Python executable of the isolated environment.


build.util module

Return the wheel metadata for a project.

Uses the prepare_metadata_for_build_wheel hook if available, otherwise build_wheel.

  • source_dir (str | PathLike[str]) -- Project source directory
  • isolated (bool) -- Whether or not to run invoke the backend in the current environment or to create an isolated one and invoke it there.
  • runner (Callable[[Sequence[str], str | None, Mapping[str, str] | None], None]) -- An alternative runner for backend subprocesses

PackageMetadata


TEST SUITE

Due to its nature, build has a somewhat complex test suite, which we will try to go through in this document.

Firstly, there are two set of tests, unit tests and integration tests. In unit tests, we test the actual code implementation. In integration tests, we test build on a few real world projects; this is mostly a sanity test.

Integration tests take a long time to run, and are not very helpful tracking down issues, so they are disabled by default. They can be enabled by passing either --run-integration or --only-integration arguments to pytest, where the latter will disable the unit tests and only run the integration ones. Even though these tests are disabled by default, they will be run in CI, where test suite run durations are not a big issue.

To run the test suite we use tox, which automates running the test suite on different environments:

tox


You can find out more about how to run tox and its arguments in the tox documentation <https://tox.readthedocs.io/>.

We have a fairly large environment matrix. We run tests for all supported Python versions and implementations, and with the module being invoked from path, sdist install, or wheel install. Additionally, we have an environment for type checking, and one to produce the documentation. There are some other extra environments, like checking the code with the minimum version of each dependency.

  • Run type checking: tox -e type
  • Only run unit tests against Python 3.9: tox -e py39
  • Run both unit and integration tests: tox -- --run-integration
  • Only run integration tests: tox -- --only-integration
  • Only run integration tests with parallel tasks: tox -- -n auto --only-integration
  • Only run unit tests against Python 3.9 with the module installed via wheel: tox -e py39-wheel


We have CI testing, where we the test suite across all supported operating systems, and have test coverage reports.

RELEASE PROCESS

You may release the project by following these steps:

1.
Bump the version src/build/__init__.py
2.
Update CHANGELOG.rst with the new version and current date
3.
•
The commit message should follow the release X.Y.Z format


4.
  • The tag title should follow the build X.Y.Z format
  • The tag body should be a plaintext version of the changelog for the current release


5.
Push the commit and tag to the repository (git push and git push --tags)
6.
Make a release on GitHub or with the gh CLI tool. Copy the release notes into the release.

If you have any questions, please look at previous releases and/or ping the other maintainers.

Author

Filipe Laíns

Copyright

2020, Filipe Laíns

January 14, 2026 1.2.2