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 fieldsWHEEL: wheel format and tags such aspy3-none-anyRECORD: the list of installed filesentry_points.txt: console scripts such ashello-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
versionas 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 separateMANIFEST.infor 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
.pyfiles; 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:
- Rust (PyO3 / cffi) → maturin
- Meson-based C/C++/Fortran/Cython → meson-python
- CMake-based builds (including many nanobind and CUDA projects) → scikit-build-core
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
- A Checklist for a New Python Package on GitHub: companion on naming, layout, metadata, and checks
- uv build backend: when
uv_buildfits - pyOpenSci: Python package build tools: frontend vs backend overview
- Thanks to Christian Heimes’s
choose-python-build-backendskill for shaping this list.
Leave a Reply