build

1.4.2 verified Tue May 12 auth: no python install: verified quickstart: stale

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

pip install build

Common errors

error ModuleNotFoundError: No module named 'build' ↓

cause 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

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

cause 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 ERROR: Could not build wheels for X, which is required to install pyproject.toml-based projects ↓

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

error Invalid pyproject.toml file ↓

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

Warnings

breaking In 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'.

breaking Support for Python 3.6 was dropped in build 0.10.0. ↓

fix Upgrade your Python environment to version 3.7 or later.

breaking The 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/')`.

breaking The 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.10s 18.8M

3.10 slim (glibc) - - 0.07s 19M

3.11 alpine (musl) - - 0.20s 20.6M

3.11 slim (glibc) - - 0.21s 21M

3.12 alpine (musl) - - 0.17s 12.5M

3.12 slim (glibc) - - 0.17s 13M

3.13 alpine (musl) - - 0.16s 12.1M

3.13 slim (glibc) - - 0.15s 13M

3.9 alpine (musl) - - 0.10s 18.6M

3.9 slim (glibc) - - 0.09s 19M

Imports

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

Quickstart stale last tested: 2026-04-23

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.