Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท pyproject and Metadata

Build Backends Compared

Understand the PEP 517 build interface and compare setuptools, hatchling, flit-core, pdm-backend, maturin and scikit-build-core, with configuration examples for each.

When you run pip install . or python -m build, something has to turn your source tree into a wheel. That something is the build backend, a Python library named in [build-system]. Different backends exist because projects differ: pure Python, C extensions, Rust, CMake, or generated code. Choosing one is a small, reversible decision, and this lesson helps you make it.

The PEP 517 interface

A backend exposes a handful of functions. The frontend (pip, build, uv build) creates an isolated temporary environment, installs build-system.requires into it, imports the module named by build-backend, and calls:

Hook Purpose
build_wheel(wheel_directory, config_settings, metadata_directory) create a .whl, return its filename
build_sdist(sdist_directory, config_settings) create a .tar.gz
get_requires_for_build_wheel(config_settings) extra build dependencies, if any
prepare_metadata_for_build_wheel(...) compute metadata without building
build_editable(...) (PEP 660) create an editable wheel
sequenceDiagram
    participant F as Frontend (pip / build / uv)
    participant E as Isolated build environment
    participant B as Backend (hatchling...)
    F->>E: create, install build-system.requires
    F->>B: import build-backend
    F->>B: build_wheel(dir)
    B-->>F: name-1.0-py3-none-any.whl

Frontends are generic; backends do the format work. Isolation makes builds reproducible.

Because the interface is standard, you can read the backend name straight out of pyproject.toml. The next example imitates what a frontend does first.

Python What a frontend learns from [build-system]

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The main backends

setuptools

The oldest and most flexible. It has handled everything: pure Python, C and C++ extensions, data files, custom commands. Since version 61 it reads the standard [project] table. Configure extras in [tool.setuptools].

TOML
[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.dynamic]
version = { attr = "mypkg.__version__" }

Choose it for existing projects, C extensions (with a small setup.py or Extension entries) and situations needing maximum compatibility. Its defaults are generous (it auto-discovers packages), which is convenient and occasionally surprising.

hatchling (Hatch)

A modern, fast, extensible backend with sensible defaults: it includes the right files, supports dynamic versions from a file or from Git tags (with a plugin), and keeps config short.

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

[tool.hatch.version]
path = "src/mypkg/__init__.py"

[tool.hatch.build.targets.wheel]
packages = ["src/mypkg"]

It is the default of uv init --lib in many templates and a good choice for pure-Python libraries and applications.

flit-core

The minimalist: pure-Python single modules or packages only, with very little configuration. The version and description come from the module's __version__ and docstring.

TOML
[build-system]
requires = ["flit_core>=3.9,<4"]
build-backend = "flit_core.buildapi"

[project]
name = "tinylib"
dynamic = ["version", "description"]

pdm-backend

The backend behind PDM, supporting the standard metadata, dynamic versions from SCM or files, and build hooks.

maturin

Builds Python packages written in Rust with PyO3 or cffi. It produces platform wheels (and can cross-build manylinux wheels).

TOML
[build-system]
requires = ["maturin>=1.7,<2"]
build-backend = "maturin"

[tool.maturin]
features = ["pyo3/extension-module"]

scikit-build-core

For CMake-based C, C++ and Fortran extensions. It replaces most of what setup.py did for scientific libraries, driving CMake and ninja.

poetry-core

The backend for Poetry projects; works with the standard [project] table in current versions or Poetry's own [tool.poetry] table in older ones.

Choosing

Pick a backend by what you build

Pure Python hatchling or flit-core
C or C++ setuptools or scikit-build-core
1 / 2

The question is rarely "which is best" but "which is the least surprising for this project". A decision helper makes the rules explicit:

Python A backend recommender

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What a backend must do for you

Whatever you choose, check that it:

  1. Reads [project] (all modern backends do).
  2. Includes your package files and excludes tests, caches and secrets. See src Layout and Package Data.
  3. Builds an sdist that can build a wheel on its own. Test that: unpack the sdist, then build from it.
  4. Handles the version the way you want (static, from a file, from Git tags).
  5. Produces a reproducible wheel (same input, same bytes, ideally with SOURCE_DATE_EPOCH).

Switching backends is mostly editing the [build-system] table and a few lines under [tool.<backend>]. Your [project] metadata stays the same. That is the payoff of the standard interface, so do not agonize over the decision.

Pin the backend sensibly

requires is evaluated at build time on the user's machine. A floating hatchling picks the newest release. Most projects set a lower bound for features they rely on, and, for old unmaintained code, an upper bound so a future major version cannot break builds. Packagers on Linux distributions prefer to build with their own versions, so avoid exact pins.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do pip and build do with the requires list in [build-system]?

    Build isolation keeps build dependencies separate from the runtime environment.
  2. 2. Which backend fits a Python package with a Rust extension built with PyO3?

    maturin is designed for Rust-based Python packages.
  3. 3. Which hook does a frontend call to create an installable binary archive?

    build_wheel creates the .whl. build_sdist creates the source archive.
  4. 4. A project has no [build-system] table. What does pip assume?

    That fallback keeps old projects working. New projects should declare the table.

Summary

  • A build backend is the library that creates wheels and sdists, called through the PEP 517 hooks.
  • Frontends (pip, build, uv build) install requires in an isolated environment and call the backend.
  • setuptools: universal and legacy-friendly; hatchling: modern pure-Python default; flit-core: minimal; maturin: Rust; scikit-build-core: CMake.
  • Switching backends mostly means editing [build-system] and one [tool.*] table.
  • Verify that the sdist builds a wheel and that the right files are included.

Next: src Layout and Package Data