Provided by: python3-build_1.2.2-1_all 
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 positional arguments
• srcdir - source directory (defaults to current directory)
python -m 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 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), there are several use cases where this is not
desirable. The main being custom environments (outside PyPI) 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/PEP
518 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 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.
setup.py sdist bdist_wheel
build is roughly the equivalent of setup.py sdist bdist_wheel but with PEP 517 support,
allowing use with projects that don't use setuptools.
Custom Behaviors
Fallback Backend
As recommended in PEP 517, if no backend is specified, build will fallback to
setuptools.build_meta:__legacy__.
INSTALLATION
build can be installed via pip or an equivalent:
$ pip install build
You can also check out the latest git tag, download a tarball from GitHub, or manually
fetch the artifacts from the project page on PyPI. 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 if accepted.
TIP:
If you prefer, or are already using virtualenv in your workflow, you can install build
with the optional virtualenv dependency:
$ pip install 'build[virtualenv]'
this way, build will use virtualenv for isolation, instead of venv. This can be
particularly useful, for example, when using automation tools that rely on virtualenv,
such as tox, or when your operating system's Python package does not include venv 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)
• Add editable to builder.get_requries_for_build's static types (PR #764, fixes issue ‐
#763)
• Include artifact attestations in our release (PR #782)
• Fix typing compatibility with typed pyproject-hooks (PR #788)
• Mark more tests with network (PR #808)
• Add more intersphinx links to docs (PR #804)
• Make uv optional for tests (PR #807 and #813)
1.2.1 (2024-03-28)
• Avoid error when terminal width is undetectable on Python < 3.11 (PR #761)
1.2.0 (2024-03-27)
• Add --installer option, supporting pip and uv. Added uv extra. (PR #751)
• Improve console output and provide -v for dependency installation (PR #749)
• Avoid compiling unused bytecode when using pip (PR #752)
• Dropped support for Python 3.7 (PR #743)
1.1.1 (2024-02-29)
• Fixed invoking outer pip from user site packages (PR #746, fixes issue #745)
• Corrected the minimum pip version required to use an outer pip (PR #746, fixes issue ‐
#745)
1.1.0 (2024-02-29)
• Use external pip if available instead of installing, speeds up environment setup with
virtualenv slightly and venv significantly. (PR #736)
• Stopped injecting wheel as a build dependency automatically, in the case of missing
pyproject.toml -- by @webknjaz. (PR #716)
• Use importlib_metadata on Python <3.10.2 for bugfixes not present in those CPython
standard libraries (not required when bootstrapping) -- by @GianlucaFicarelli. (PR ‐
#693, fixes issue #692)
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, fixes issue #674)
1.0.0 (2023-09-01)
• Removed the toml library fallback; toml can no longer be used as a substitute for tomli
(PR #567)
• Added runner parameter to util.project_wheel_metadata (PR #566, fixes issue #553)
• Modified ProjectBuilder constructor signature, added alternative ProjectBuilder.from_env
constructor, redefined env.IsolatedEnv interface, and exposed env.DefaultIsolatedEnv,
replacing env.IsolatedEnvBuilder. The aim has been to shift responsibility for
modifying the environment from the project builder to the IsolatedEnv entirely and to
ensure that the builder will be initialised from an IsolatedEnv in a consistent manner.
Mutating the project builder is no longer supported. (PR #537)
• virtualenv is no longer imported when using -n, for faster builds (PR #636, fixes issue
#510)
• The SDist now contains the repository contents, including tests. Flit-core 3.8+
required. (PR #657, #661, fixes issue #656)
• The minimum version of importlib-metadata has been increased to 4.6 and Python 3.10 due
to a bug in the standard library version with URL requirements in extras. This is still
not required for 3.8 when bootstrapping (as long as you don't have URL requirements in
extras). (PR #631, fixes issue #630)
• Docs now built with Sphinx 7 (PR #660)
• Tests now contain a network marker (PR #649, fixes issue #648)
• Config-settings are now passed to get_requires* hooks, fixing a long standing bug. If
this affects your setuptools build, you can use -C--build-option=<cmd>
-C--build-option=<option> to workaround an issue with Setuptools not allowing
unrecognised build options when running this hook. (PR #627, fixes issue ##264)
• Test on Python 3.12 betas/RCs (PR #624)
• Filter out malicious files when extracting tar archives when Python supports it (PR ‐
#609)
• Specify encoding, fixing issues when PYTHONWARNDEFAULTENCODING is set. (PR #587, fixes
issue #577)
• Ruff is now used for linting.
0.10.0 (2023-01-11)
• Replace pep517 dependency with pyproject_hooks, into which pep517 has been renamed (PR ‐
#539, Fixes #529)
• Change build backend from setuptools to flit (PR #470, Fixes #394)
• Dropped support for Python 3.6 (PR #532)
0.9.0 (2022-10-27)
• Hide a Python 3.11.0 unavoidable warning with venv (PR #527)
• Fix infinite recursion error in check_dependency with circular dependencies (PR #512,
Fixes #511)
• Only import colorama on Windows (PR #494, Fixes #493)
• Flush output more often to reduce interleaved output (PR #494)
• Small API cleanup, like better _all__ and srcdir being read only. (PR #477)
• Only use importlib_metadata when needed (PR #401)
• Clarify in printout when build dependencies are being installed (PR #514)
0.8.0 (2022-05-22)
• Accept os.PathLike[str] in addition to str for paths in public API (PR #392, Fixes #372)
• Add schema validation for build-system table to check conformity with PEP 517 and PEP
518 (PR #365, Fixes #364)
• Better support for Python 3.11 (sysconfig schemes PR #434, PR #463, tomllib PR #443,
warnings PR #420)
• Improved error printouts (PR #442)
• Avoid importing packaging unless needed (PR #395, Fixes #393)
Breaking Changes
• Failure to create a virtual environment in the build.env module now raises
build.FailedProcessError (PR #442)
0.7.0 (2021-09-16)
• Add build.util module with an high-level utility API (PR #340)
0.6.0.post1 (2021-08-05)
• Fix compatibility with Python 3.6 and 3.7 (PR #339, Fixes #338)
0.6.0 (2021-08-02)
• Improved output (PR #333, Fixes #142)
• The CLI now honors NO_COLOR (PR #333)
• The CLI can now be forced to colorize the output by setting the FORCE_COLOR environment
variable (PR #335)
• Added logging to build and build.env (PR #333)
• Switch to a TOML v1 compliant parser (PR #336, Fixes #308)
Breaking Changes
• Dropped support for Python 2 and 3.5.
0.5.1 (2021-06-22)
• Fix invoking the backend on an inexistent output directory with multiple levels (PR ‐
#318, Fixes #316)
• When building wheels via sdists, use an isolated temporary directory (PR #321, Fixes ‐
#320)
0.5.0 (2021-06-19)
• Add ProjectBuilder.metadata_path helper (PR #303, Fixes #301)
• Added a build.__main__.build_package_via_sdist method (PR #304)
• Use appropriate installation scheme for Apple Python venvs (PR #314, Fixes #310)
Breaking Changes
• Binary distributions are now built via the sdist by default in the CLI (PR #304, Fixes ‐
#257) - python -m build will now build a sdist, extract it, and build a wheel from the
source
• As a side-effect of PR #304, build.__main__.build_package no longer does CLI error
handling (print nice message and exit the program)
• Importing build.__main__ no longer has any side-effects, it no longer overrides
warnings.showwarning or runs colorama.init on import (PR #312)
0.4.0 (2021-05-23)
• Validate that the supplied source directory is valid (PR #260, Fixes #259)
• Set and test minimum versions of build's runtime dependencies (PR #267, Fixes #263)
• Use symlinks on creating venv's when available (PR #274, Fixes #271)
• Error sooner if pip upgrade is required and fails (PR #288, Fixes #256)
• Add a runner argument to ProjectBuilder (PR #290, Fixes #289)
• Hide irrelevant pep517 error traceback and improve error messages (PR #296)
• Try to use colorama to fix colors on Windows (PR #300)
Breaking Changes
• As a side-effect of PR #260, projects not containing either a pyproject.toml or setup.py
will be reported as invalid. This affects projects specifying only a setup.cfg, such
projects are recommended to add a pyproject.toml. The new behavior is on par with what
pip currently does, so if you are affected by this, your project should not be pip
installable.
• The --skip-dependencies option has been renamed to --skip-dependency-check (PR #297)
• The skip_dependencies argument of build.__main__.build_package has been renamed to
skip_dependency_check (PR #297)
• build.ConfigSettings has been renamed to build.ConfigSettingsType (PR #298)
• build.ProjectBuilder.build_dependencies to build.ProjectBuilder.build_system_requires
(PR #284, Fixes #182)
• build.ProjectBuilder.get_dependencies to build.ProjectBuilder.get_requires_for_build (PR
#284, Fixes #182)
0.3.1 (2021-03-09)
• Support direct usage from pipx run in 0.16.1.0+ (PR #247)
• Use UTF-8 encoding when reading pyproject.toml (PR #251, Fixes #250)
0.3.0 (2021-02-19)
• Upgrade pip based on venv pip version, avoids error on Debian Python 3.6.5-3.8 or issues
installing wheels on Big Sur (PR #229, PR #230, Fixes #228)
• Build dependencies in isolation, instead of in the build environment (PR #232, Fixes ‐
#231)
• Fallback on venv if virtualenv is too old (PR #241)
• Add metadata preparation hook (PR #217, Fixes #130)
0.2.1 (2021-02-09)
• Fix error from unrecognised pip flag on Python 3.6.0 to 3.6.5 (PR #227, Fixes #226)
0.2.0 (2021-02-07)
• Check dependencies recursively (PR #183, Fixes #25)
• Build wheel and sdist distributions in separate environments, as they may have different
dependencies (PR #195, Fixes #194)
• Add support for pre-releases in check_dependency (PR #204, Fixes #191)
• Fixes console scripts not being available during build (PR #221, Fixes #214)
• Do not add the default backend requirements to requires when no backend is specified (PR
#177, Fixes #107)
• Return the sdist name in ProjectBuild.build (PR #197)
• Improve documentation (PR #178, PR #203)
• Add changelog (PR #219, Fixes #169)
Breaking changes
• Move config_settings argument to the hook calls (PR #218, Fixes #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
exception build.BuildBackendException(exception, description=None, exc_info=(None, None,
None))
Bases: Exception
Exception raised when a backend operation fails.
exception build.BuildException
Bases: Exception
Exception raised by build.ProjectBuilder.
exception build.BuildSystemTableValidationError
Bases: BuildException
Exception raised when the [build-system] table in pyproject.toml is invalid.
exception build.FailedProcessError(exception, description)
Bases: Exception
Exception raised when a setup or preparation operation fails.
class build.ProjectBuilder(source_dir, python_executable='/usr/bin/python3.12',
runner=<function default_subprocess_runner>)
Bases: object
The PEP 517 consumer API.
Parameters
• source_dir (Union[str, PathLike[str]]) -- The source directory
• python_executable (str) -- The python executable where the backend lives
• runner (Callable[[Sequence[str], Optional[str], Optional[Mapping[str,
str]]], 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(distribution, output_directory, config_settings=None,
metadata_directory=None)
Build a distribution.
Parameters
• distribution (Literal['sdist', 'wheel', 'editable']) --
Distribution to build (sdist or wheel)
• output_directory (Union[str, PathLike[str]]) -- Directory to put
the built distribution in
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]])
-- 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
Return type
str
Returns
The full path to the built distribution
property build_system_requires: set[str]
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.
check_dependencies(distribution, config_settings=None)
Return the dependencies which are not satisfied from the combined set of
build_system_requires and get_requires_for_build() for a given distribution.
Parameters
• distribution (Literal['sdist', 'wheel', 'editable']) --
Distribution to check (sdist or wheel)
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]])
-- Config settings for the build backend
Return type
set[tuple[str, ...]]
Returns
Set of variable-length unmet dependency tuples
classmethod from_isolated_env(env, source_dir, runner=<function
default_subprocess_runner>)
Return type
TypeVar(_TProjectBuilder, bound= ProjectBuilder)
get_requires_for_build(distribution, config_settings=None)
Return the dependencies defined by the backend in addition to
build_system_requires for a given distribution.
Parameters
• distribution (Literal['sdist', 'wheel', 'editable']) --
Distribution to get the dependencies of (sdist or wheel)
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]])
-- Config settings for the build backend
Return type
set[str]
metadata_path(output_directory)
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.
Parameters
output_directory (Union[str, PathLike[str]]) -- Directory to put the
metadata distribution in
Return type
str
Returns
The path of the metadata directory
prepare(distribution, output_directory, config_settings=None)
Prepare metadata for a distribution.
Parameters
• distribution (Literal['sdist', 'wheel', 'editable']) --
Distribution to build (must be wheel)
• output_directory (Union[str, PathLike[str]]) -- Directory to put
the prepared metadata in
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]])
-- Config settings for the build backend
Return type
str | None
Returns
The full path to the prepared metadata directory
property python_executable: str
The Python executable used to invoke the backend.
property source_dir: str
Project source directory.
exception build.TypoWarning
Bases: Warning
Warning raised when a possible typo is found.
build.check_dependency(req_string, ancestral_req_strings=(), parent_extras=frozenset({}))
Verify that a dependency and all of its dependencies are met.
Parameters
• req_string (str) -- Requirement string
• parent_extras (Set[str]) -- Extras (eg. "test" in myproject[test])
Yields Unmet dependencies
Return type
Iterator[tuple[str, ...]]
build.env module
class build.env.DefaultIsolatedEnv(*, installer='pip')
Bases: IsolatedEnv
Isolated environment which supports several different underlying implementations.
install(requirements)
Install packages from PEP 508 requirements in the isolated build
environment.
Parameters
requirements (Collection[str]) -- PEP 508 requirement specification
to install
Note 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.
Return type
None
make_extra_environ()
Generate additional env vars specific to the isolated environment.
Return type
dict[str, str]
property path: str
The location of the isolated build environment.
property python_executable: str
The python executable of the isolated build environment.
class build.env.IsolatedEnv(*args, **kwargs)
Bases: Protocol
Isolated build environment ABC.
abstract make_extra_environ()
Generate additional env vars specific to the isolated environment.
Return type
Mapping[str, str] | None
abstract property python_executable: str
The Python executable of the isolated environment.
build.util module
build.util.project_wheel_metadata(source_dir, isolated=True, *, runner=<function
quiet_subprocess_runner>)
Return the wheel metadata for a project.
Uses the prepare_metadata_for_build_wheel hook if available, otherwise build_wheel.
Parameters
• source_dir (Union[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], Optional[str], Optional[Mapping[str,
str]]], None]) -- An alternative runner for backend subprocesses
Return type
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.
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.
Some examples commands for this project:
• 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.
Make a release commit with the changes made above
• The commit message should follow the release X.Y.Z format
4.
Make a signed tag (git tag --sign X.Y.Z)
• 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
2024, Filipe Laíns