Build backends for pure Python packages

You want others to pip install your library. Something must build an sdist and a wheel. Today that something is declared in pyproject.toml as the build backend.

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

Not every repo has this file yet. Many older ones still lean on setup.py. For new work, put the backend here. This post picks among pure-Python backends: hatchling, uv_build, flit-core, and when to stay on setuptools. Compiled packages need a different chooser; see the closing note for now.

Two jobs, one interface

A source build uses two programs.

The frontend is the tool you run: pip, uv, or python -m build. It creates a temporary build environment, installs what the project asked for, and drives the process.

The backend turns the source tree into an sdist and a wheel. It is usually a package from PyPI (hatchling, flit-core, uv_build, setuptools), imported by the name in build-backend.

PEP 518 put build requirements in [build-system].requires. PEP 517 defined the hooks the frontend calls. Any compliant frontend can drive any compliant backend. That is why a wrong call for a pure-Python package is cheap to reverse: change two lines, rebuild, and pip or uv will not care which backend produced the wheel.

The backend does not create or manage your venv (Python virtual environment), resolve application dependencies, or upload to PyPI. Environment managers and workflow tools (Hatch, PDM, Poetry, uv) sit beside that interface. Here we care about the backend string in pyproject.toml.

For more on how those hooks run, including that a backend can add requirements at build time, see How Python Packages Build Themselves. This post answers a different question: which backend should a new pure-Python project declare?

A tiny package, built with hatchling

Here is a minimal layout. The import package lives under src/, which keeps the project root free of an importable tree and matches what several modern backends expect by default:

hello-hatch/
├── pyproject.toml
├── README.md
└── src/
    └── hello_hatch/
        └── __init__.py

pyproject.toml declares hatchling as the backend and static project metadata: values written literally in the file, not computed at build time.

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

[project]
name = "hello-hatch"
version = "0.1.0"
description = "Tiny pure-Python package for a build-backend walkthrough"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"

[project.scripts]
hello-hatch = "hello_hatch:main"

The module can be a few lines:

"""Tiny pure-Python package for a build-backend walkthrough."""

__version__ = "0.1.0"


def main() -> None:
    print(f"hello-hatch {__version__}")

Build with a frontend. uv build and python -m build both speak PEP 517; either works:

$ uv build
Building source distribution...
Building wheel from source distribution...
Successfully built dist/hello_hatch-0.1.0.tar.gz
Successfully built dist/hello_hatch-0.1.0-py3-none-any.whl

The wheel name ends in py3-none-any. That tag means: py3 (any Python 3), none (no native ABI), any (any platform). That is the pure-Python contract: nothing compiled.

Open the wheel (it is a zip file) and you will see your package plus a .dist-info folder. That folder is the install metadata:

  • METADATA: name, version, and other project fields
  • WHEEL: wheel format and tags such as py3-none-any
  • RECORD: the list of installed files
  • entry_points.txt: console scripts such as hello-hatch

There is no compiled code in this wheel.

The hatchling >= 1.26 pin in [build-system] follows the PyPA Writing your pyproject.toml recommendation. During an isolated build the frontend installs that requirement (and hatchling’s own dependencies) into a throwaway environment before calling the backend. You do not need hatchling installed in your everyday venv for uv build to succeed.

Install the wheel in a clean environment and run the console script once. That checks the package layout and the entry point, not only that a file appeared under dist/:

$ uv venv /tmp/hello-hatch-venv
$ uv pip install --python /tmp/hello-hatch-venv dist/hello_hatch-0.1.0-py3-none-any.whl
$ /tmp/hello-hatch-venv/bin/hello-hatch
hello-hatch 0.1.0

Static metadata first

Most [project] fields should be written as literals: name, version, dependencies, requires-python. That is static metadata. The backend copies it into the wheel.

Sometimes a field must be computed at build time, such as a version from a Git tag, or a README assembled from parts. Mark those fields in dynamic and configure the backend to fill them. Until you need that, keep the version in [project] as a string. Static metadata is easier to read in review, and every backend in this post supports it.

When version-from-VCS becomes the next requirement, that is a reason to prefer hatchling (with hatch-vcs) over uv-build, which does not do dynamic or VCS versions. It is not a reason to stay on a hand-maintained setup.py solely for the version string.

A decision rule, not a catalog

The PyPA tool recommendations deliberately do not pick a single pure-Python winner. They list several popular backends and leave the choice to the project. For a new package, a rule of thumb still helps. A compact view of the pure-Python options:

Backend Dynamic / VCS version Plugins / hooks Best for
hatchling yes (e.g. hatch-vcs) yes default; room to grow
pdm-backend yes (built-in SCM) yes teams already on PDM
uv-build no no simple static packages already using uv
flit-core __version__ (and description) only no smallest config
setuptools yes (setuptools-scm) yes existing projects that already build

PEP 517 builds are isolated: the frontend installs only what you list in [build-system].requires into a throwaway environment. Put the backend there (and later any build-time helper such as hatch-vcs). If it is not in requires, it is not available at build time.

Start with hatchling

hatchling is the safe general-purpose default for pure Python.

  • It is the backend in PyPA’s full pyproject.toml worked example, and one of the two PyPA-maintained backends alongside setuptools.
  • It supports static metadata and full dynamic metadata. Version from a Git tag is a common need; pair hatchling with hatch-vcs and mark version as dynamic when you outgrow a literal string in [project].
  • It has a real plugin and build-hook system if you later need custom steps.
  • Its defaults are strict in useful ways: sdist contents follow .gitignore (no separate MANIFEST.in for the usual case), and wheel inclusion errs rather than silently shipping every directory that looks like a package. Why Hatch? compares those defaults with setuptools in more detail. Reproducible builds are on by default.

If you are unsure, put hatchling in [build-system] and move on.

Prefer uv-build when the project is simple and already on uv

uv-build (uv_build) is Astral’s native backend. It is pure-Python only, optimized for speed, and the default of uv init for new packages.

Use it when all of these hold:

  • The package is pure Python (only .py files; nothing to compile).
  • Metadata is static: no VCS-driven version, no build-time generation of files that do not already exist in the tree.
  • You are fine with its layout expectations (by default one module under src/<package_name>/).

The documentation’s [build-system] block looks like this:

[build-system]
requires = ["uv_build>=0.13.9,<0.14"]
build-backend = "uv_build"

uv init writes both a minimum and a maximum version for uv_build, because that package moves in step with uv. If you write [build-system] yourself, a minimum version is enough. Stick with uv_build only while the package stays simple and static. If you need a version from git tags, custom build steps, or a different folder layout, switch to hatchling.

Prefer flit-core when you want the smallest backend

flit-core is deliberately minimal. No plugin system, no compiled extensions, little configuration.

It supports one important dynamic field: reading the version (and description) from the module, for example a __version__ string, with dynamic = ["version", "description"]. Beyond that, keep metadata static.

[build-system]
requires = ["flit_core >= 3.12.0, <5"]
build-backend = "flit_core.buildapi"

Choose flit-core for a small, pure-Python package when you want the least machinery, not because hatchling is “too big” for production, but because the project truly does not need hatchling’s extras.

Setuptools: stay if it already works

setuptools is not deprecated. It is still a valid PEP 517 backend. What is deprecated is running python setup.py sdist, bdist_wheel, or install by hand. Build with a frontend (uv build, python -m build, or pip). Put new metadata in [project]. See Is setup.py deprecated?.

New pure-Python project: prefer hatchling (or uv-build / flit-core above). Reasons:

  • Clearer defaults for what goes in the sdist and wheel
  • Reproducible builds by default
  • Editable installs that tools understand without extra setuptools config
  • Narrower backends change less often than setuptools, which ships many major versions a year and builds a huge share of PyPI. A bad release there breaks many builds.

Existing setuptools project that already ships cleanly: no rush. Migrate when you want those defaults, or one pyproject.toml without setup.cfg / MANIFEST.in. Do not migrate only on principle. Switching backends later is usually a small config change, not a rewrite of the project.

Poetry: whole workflow, not only a backend

poetry-core is a valid build backend. Choosing it usually means using Poetry’s whole workflow, not only a [build-system] line.

Poetry 2.0 supports the standard [project] table. Older tutorials often use [tool.poetry] only.

Already shipping with Poetry on a pure-Python project? Staying is fine. Want a small stack (for example uv plus hatchling or flit-core)? Prefer that instead.

PDM-backend: often comes with the PDM workflow

pdm-backend is another modern PEP 621 backend on PyPA’s list. It supports plugins, editable installs, and built-in SCM versioning ([tool.pdm.version] with source = "scm"), so you do not need a separate hatch-vcs-style plugin for git tags. Any PEP 517 frontend can drive it:

[build-system]
requires = ["pdm-backend >= 2.4.0"]
build-backend = "pdm.backend"

Choosing it often goes with the PDM workflow tool (lockfiles, pdm build), though the backend also works alone. For a new project without that stack already in place, this post still defaults to hatchling; if your team already uses PDM, pdm-backend is a solid fit.

What this post does not choose

If the project contains extension modules (C, C++, Cython, Fortran, Rust, CUDA), the primary selector is the native build system, not the pure-Python checklist above:

PyPA’s tool recommendations group those the same way. Cython’s own compilation guide now steers new projects toward modern backends (with Meson common in the scientific stack) rather than treating setuptools as the default.

A later post will cover that chooser. This one stays on pure Python.

Takeaway

For pure Python, pick hatchling unless you have a clear reason for uv-build or flit-core. Declare it in [build-system], build once with a frontend, and treat the backend as swappable. For this class of package, a later switch is usually a small config change.

Further reading

Response

  1. […] uv-build, and flit-core, and when to stay on setuptools, is covered in another companion post Build backends for pure Python packages. This checklist uses hatchling: it is the backend in PyPA’s worked pyproject.toml example, it […]

Leave a Reply