PEP 517 defines a standard hook API that Python build backends implement and build frontends call. Mandatory hooks are `build_wheel` and `build_sdist`; optional hooks like `get_requires_for_build_wheel`, `prepare_metadata_for_build_wheel`, and `build_editable` (added by PEP 660) cover dependency declaration, metadata extraction, and editable installs. Any PEP 517-compliant frontend (pip, uv, build) can drive any compliant backend (setuptools, hatchling, flit_core, uv_build, maturin) through the same interface.

PEP 518 introduced pyproject.toml in 2016 and defined the `[build-system]` table that declares a project's build dependencies in a tool-agnostic way. Before PEP 518, the only way to declare build-time requirements was inside setup.py itself, which created a chicken-and-egg problem: the installer had to run setup.py to learn what setup.py needed. PEP 518 moved that declaration to static TOML so frontends can install build dependencies into an isolated environment before the build starts.

What is the difference between PEP 517 and PEP 518?

PEP 518 introduced the file (`pyproject.toml`) and the table (`[build-system]`) that declares build-time dependencies. PEP 517 introduced the hook API that frontends use to drive backends. PEP 518 came first (2016); PEP 517 (2017) built on it by specifying the `build-backend` key inside the same `[build-system]` table and the function signatures every backend must implement. The two are usually cited together because most projects use both at once.

What does PEP 517 compatibility mean for a tool?

A PEP 517-compliant build frontend (pip 19.0+, uv, `python -m build`, Poetry, Hatch, PDM) reads the `[build-system]` table, installs the listed `requires` into an isolated environment, imports the named `build-backend`, and calls its hook functions. A PEP 517-compliant build backend (setuptools, hatchling, flit_core, uv_build, maturin, scikit-build-core, poetry-core) exposes those hook functions so any frontend can drive it without special-case code.

Is setup.py still needed with PEP 517?

No. Projects that declare a `build-backend` in pyproject.toml do not need a setup.py file. setuptools-based projects can put all of their configuration into the `[project]` table (PEP 621) and `[tool.setuptools]` keys; setup.py is only required for legacy build logic that hasn't been ported. Commands like `python setup.py install` and `python setup.py sdist` are deprecated; use `pip install .` or `python -m build` instead.

What is PEP 517/518 compatibility?

by Tim Hopper

Packaging

PEP 518 introduced pyproject.toml in 2016 and defined the [build-system] table for declaring build-time dependencies in a tool-agnostic way. PEP 517 followed in 2017 and defined the hook API that every build backend implements and every build frontend calls. Together they replaced the setup.py-only build model and made it possible to use Hatchling, flit_core, poetry-core, uv_build, maturin, or any other backend with the same install commands.

The problem the PEPs solved

Before PEP 518, every Python package was built by running setup.py, a Python script that imported setuptools (or the older distutils) and called functions to declare metadata, list dependencies, and produce build artifacts. The installer had to execute setup.py to discover anything about the package, including which build dependencies the script itself needed. That ordering created a circular requirement: setuptools had to already be present before the installer could ask the project what it required.

The setup.py model also coupled the entire ecosystem to setuptools. Alternative build systems existed but had to wrap or mimic the setuptools entry points to work with pip. Replacing setuptools meant replacing the whole installer integration, not just the build step.

What PEP 518 added

PEP 518 introduced the pyproject.toml file and reserved a [build-system] table for build configuration:

[build-system]
requires = ["setuptools>=61", "wheel"]

The requires key lists packages the frontend must install into an isolated build environment before invoking the build. Because the file is static TOML, the frontend can read it without executing project code, and the build step starts with a known set of dependencies already in place.

pip 10.0 (April 2018) was the first installer to honor [build-system].requires. By that point, the file had a clear job even before any non-setuptools backends adopted it.

What PEP 517 added

PEP 517 extended the same [build-system] table with a build-backend key and defined the functions every backend must expose:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

build-backend names a Python object using the module[:object] syntax. The frontend imports that object and calls its hook functions, the most important of which are:

build_wheel(wheel_directory, ...) produces a wheel in the given directory.
build_sdist(sdist_directory, ...) produces an sdist source distribution.
get_requires_for_build_wheel and get_requires_for_build_sdist declare any extra dependencies the backend needs, beyond the static requires list.
prepare_metadata_for_build_wheel lets a frontend extract metadata without producing the full wheel.

PEP 660 later added a build_editable hook so backends could implement editable installs the same way they implement regular wheels. pip 19.0 (January 2019) was the first release to support the full PEP 517 hook API; pip 21.3 (October 2021) added PEP 660 support.

How frontends and backends fit together

PEP 517 split package building into two halves: the build frontend (the tool a developer invokes) and the build backend (the library that produces artifacts).

A typical pip install . flow now looks like:

pip reads [build-system] from pyproject.toml.
pip creates an isolated build environment and installs the packages listed in requires.
pip imports the object named in build-backend and calls build_wheel.
The backend produces a wheel; pip installs it into the target environment.

Any compliant frontend can drive any compliant backend, so swapping Hatchling for flit_core, or pip for uv, changes which packages handle each step without changing the contract between them.

Map tools to each role

Role	Tools
Build frontend	pip, uv, build, Hatch, Poetry, PDM
Build backend	setuptools, Hatchling, flit_core, poetry-core, uv_build, maturin, scikit-build-core

Most projects do not need to think about the distinction once it is configured. pip install ., uv pip install ., and python -m build all go through the same interface; the project’s [build-system] table decides which backend gets called.

Spell out what compatibility means

A frontend is compatible if it reads the [build-system] table, installs the listed requires into an isolated environment, and calls the hooks defined by build-backend. A backend is compatible if it exposes the mandatory hook functions and can be imported from a freshly installed environment. Most active Python build tools have been compatible since 2019 or earlier; the question now is rarely whether a tool supports the standards but which optional hooks (PEP 660 editable installs, in-tree build backends, build isolation toggles) it implements.

What is a build backend? walks through what backends actually do.
What is a build frontend? covers the other side of the interface.
What is PEP 621 compatibility? explains how project metadata moved into the same file.
What is PEP 660? standardized editable installs on top of PEP 517.
Should I run python setup.py? covers the deprecated commands these PEPs replaced.
pyproject.toml reference documents every table in the file, including [build-system].

Learn More

Last updated on May 7, 2026

What is PEP 503?What is PEP 609?

Please submit corrections and feedback...