Why Python Needs pyproject.toml: Understanding Build System Dependencies

Summary

This PEP explains how Python packages should declare their build‑system dependencies using a new configuration file, pyproject.toml. The file stores the minimal set of requirements needed to run the build backend, allowing tools such as pip to install those dependencies beforehand.

Basic Principles

Historically, distutils was the default build tool, later superseded by setuptools. Both rely on a setup.py script that is executed to build and distribute a package. While distutils has no external dependencies, setuptools introduces a paradox: the setup.py script may require dependencies that are unknown until the script is run, but the script cannot be run without those dependencies. setuptools tries to solve this with the setup_requires argument, but this approach has many drawbacks, such as requiring setuptools itself, creating complex delayed‑import mechanisms, and forcing users to manage both pip and setuptools configurations.

Consequently, setup_requires is rarely used, and projects often resort to manual pre‑installation of required tools.

Specification

The build‑system dependencies are stored in a pyproject.toml file written in TOML format. TOML was chosen because it is human‑readable, flexible, and less complex than alternatives like JSON, YAML, or INI.

The file contains a [build-system] table. The only required key is requires, which holds a list of PEP 508 dependency specifications needed to execute the build backend.

Example JSON schema matching the TOML data:

Typical pyproject.toml for a setuptools‑based project:

When the file is absent, tools fall back to this example configuration.

Other top‑level tables are preserved for future PEPs. The [tool] namespace allows tool‑specific configuration, e.g., [tool.flit].

Rejected Ideas

Semantic Versioning – initially proposed to version the configuration file, but deemed unnecessary.

Deeper Namespace – a top‑level [Package] table was considered but later dropped.

Alternative Table Names – [build] was suggested as a shorter name but lacked clarity.

Other File Formats

JSON – rejected because it is not as human‑friendly as TOML.

YAML – rejected due to complexity, length, and safety concerns.

Configparser (INI) – rejected because of inconsistent support across Python versions.

Python syntax – rejected because it ties the format to Python itself, limiting cross‑tool usage.

Various alternative file names were discussed (e.g., pysettings.toml, pypa.toml, pybuild.toml), but none were adopted.

Original English text: https://www.python.org/dev/peps/pep-0518/