build

library1.4.2pypypi✓ verified 52d ago

A simple, correct Python build frontend. Current version: 1.4.2. Released on March 25, 2026. Maintained by the Python Packaging Authority (PyPa).

devops

pip install build

github ↗package ↗homepage ↗changelog ↗

Install & Compatibility

Where this runs

tested against v1.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.143s · 19MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.8s · import 0.131s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

build

✓ import build

Ensure 'build' is installed in your environment before importing.

Builds the package in the current directory, generating a source distribution and wheel in the 'dist/' directory.

import build # Build the package in the current directory build.build() # This will build the package in an isolated environment, generating a source distribution and wheel in the 'dist/' directory.

build --version

Debug

Known issues

breakingIn build 0.10.0, the 'pep517' dependency was replaced with 'pyproject_hooks', and the build backend was changed from 'setuptools' to 'flit'.

fix

Update your build dependencies to include 'pyproject_hooks' and adjust your build backend to 'flit'.

affects: 0.10.0

breakingSupport for Python 3.6 was dropped in build 0.10.0.

fix

Upgrade your Python environment to version 3.7 or later.

affects: 0.10.0

breakingThe function `build.build()` does not exist in the `python-build` package's public API. The primary programmatic interface for building packages is `build.ProjectBuilder().build()`.

fix

Replace `build.build()` with a call to `build.ProjectBuilder().build()`. For example, `from build import ProjectBuilder; ProjectBuilder().build('./', 'dist/')`.

affects: 0.10.0

breakingThe top-level `build` function in the `build` module was removed. Use `build.ProjectBuilder().build()` instead.

fix

Replace `build.build()` with `build.ProjectBuilder().build()` in your script.

affects: 0.10.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'build'

This error occurs when the 'build' package itself has not been installed in your Python environment, and you try to run it using `python -m build` or import it directly.

fix

You need to install the 'build' package using pip: `pip install build`

No module named build.__main__; 'build' is a package and cannot be directly executed

This error typically arises when there's an older or conflicting version of the 'build' package installed, or if a local directory named 'build' shadows the actual package, preventing the `__main__` module from being found during execution via `python -m build`.

fix

Ensure you have the latest version of the 'build' package by running `pip install --upgrade build`. If the problem persists, check your `PYTHONPATH` environment variable for conflicting entries or rename any local directories named 'build' that might be interfering.

ERROR: Could not build wheels for X, which is required to install pyproject.toml-based projects

This is a generic error indicating that the 'build' frontend (or pip which uses it) failed to compile a wheel for a specific package (represented by 'X'), usually due to missing system-level dependencies (like compilers or development headers) or build-time Python dependencies not being correctly specified or installed in the isolated build environment.

fix

Identify the specific package 'X' causing the issue and consult its documentation for build prerequisites. Common fixes include installing development headers (e.g., `sudo apt-get install python3-dev` on Debian/Ubuntu, `sudo dnf install python3-devel` on Red Hat/Fedora, or Xcode command-line tools on macOS) and ensuring that all build-time Python dependencies are correctly listed in the `pyproject.toml`'s `[build-system] requires` section. You might also try updating pip and setuptools: `pip install --upgrade pip setuptools`.

Invalid pyproject.toml file

The `pyproject.toml` file, which specifies build system requirements and project metadata, contains a syntax error or uses a deprecated format that the `build` tool or its backend cannot parse.

fix

Carefully review your `pyproject.toml` file for any typos, incorrect syntax, or adherence to deprecated metadata formats (e.g., for the `license` field). Refer to the official Python Packaging User Guide for the correct `pyproject.toml` specification. Tools like `toml-cli` can help validate the TOML syntax.

Upgrade

Version history

1.5.0latest on PyPI

Audit

Dependencies

pyproject_hooksrequiredReplaces the 'pep517' dependency; 'pep517' has been renamed to 'pyproject_hooks' in build 0.10.0. ([build.pypa.io](https://build.pypa.io/en/latest/changelog.html?utm_source=openai))

Agent activity

20 hits · last 30 days

node

seranking-bot

ahrefsbot

Amazon

amazonbot

Resources

githubhttps://github.com/pypa/build ↗

packagehttps://pypi.org/project/build/ ↗

homepagehttps://build.pypa.io ↗

changeloghttps://build.pypa.io/en/stable/changelog.html ↗