Textbook of Python

pyproject.toml is the modern standard configuration file for Python projects, introduced by PEP 518 (2016) and expanded by PEP 621 (2021). It replaces the older setup.py, setup.cfg, and requirements.txt approach with a single, declarative TOML file that specifies build system requirements, project metadata, dependencies, and tool configuration.

The [build-system] table specifies which build backend to use (e.g., setuptools, hatchling, flit-core, pdm-backend). The [project] table holds metadata: name, version, description, author, license, Python version requirement, and dependencies. The [project.optional-dependencies] table defines extras (e.g., dev, test, docs). Many tools — pytest, mypy, ruff, black, isort — read their configuration from [tool.toolname] sections in pyproject.toml.

The shift to pyproject.toml consolidates what used to be scattered across multiple files (setup.py, setup.cfg, MANIFEST.in, tox.ini, pytest.ini, mypy.ini) into a single source of truth. It also enables declarative builds — no arbitrary Python code in setup.py — which makes projects more reproducible and secure. Most new Python projects should use pyproject.toml exclusively.