BUILD(1) build BUILD(1)

build - build 1.0.3

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.


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] [--sdist] [--wheel] [--outdir PATH]
                [--skip-dependency-check] [--no-isolation] [--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
  • --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
  • --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.

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.

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.

As recommended in PEP 517, if no backend is specified, build will fallback to setuptools.build_meta:__legacy__.

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. The git tags are recommended for redistribution and are PGP-signed with one of the following keys:

•
3DCE51D60930EBA47858BA4146F633CBB0EB4BF2 (Filipe Laíns)

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).



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.

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

  • 3.7
  • 3.8
  • 3.9
  • 3.10
  • 3.11
  • PyPy3

•
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)

  • 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.

  • 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)

  • 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)

  • 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)

•
Add build.util module with an high-level utility API (PR #340)

•
Fix compatibility with Python 3.6 and 3.7 (PR #339, Fixes #338)

  • 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.

  • 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)

  • 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)

  • 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)

  • 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)

  • 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)

•
Fix error from unrecognised pip flag on Python 3.6.0 to 3.6.5 (PR #227, Fixes #226)

  • 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)

  • 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

  • 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

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

  • Misc improvements
  • Added documentation

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

•
Initial release

build module

build - A simple, correct PEP 517 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 (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 a distribution.
  • distribution (str) -- 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 (Optional[str]) -- 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 (str) -- Distribution to check (sdist or wheel)
  • config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]]) -- 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 (str) -- Distribution to get the dependencies of (sdist or wheel)
  • config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]]) -- Config settings for the build backend

set[str]


Log a message.

The default implementation uses the logging module but this function can be overridden by users to have a different implementation.

message (str) -- Message to output
None


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 (Union[str, PathLike[str]]) -- Directory to put the metadata distribution in
str
The path of the metadata directory


Prepare metadata for a distribution.
  • distribution (str) -- 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

Optional[str]
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

An isolated environment which combines venv and virtualenv with pip.

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


Prints message

The default implementation uses the logging module but this function can be overwritten by users to have a different implementation.

msg -- Message to output
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.
Optional[Mapping[str, str]]


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 (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

PackageMetadata


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.

  • 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.

As this project is critical to the Python ecosystem's supply chain security, all releases are PGP signed with one of the keys listed in the installation page. Before releasing please make sure your PGP key is listed there, and preferably signed by one of the other key holders. If your key is not signed by one of the other key holders, please make sure the PR that added your key to the installation page was approved by at least one other maintainer.

After that is done, you may release the project by following these steps:

1.
Bump the versions in pyproject.toml and 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.
Build the Python artifacts (python -m build)
7.
Sign and push the artifacts to PyPI (twine upload -s dist/*)

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

Filipe Laíns

2024, Filipe Laíns

January 31, 2024 1.0.3