In this lesson, you will learn how to evaluate and select the right build backend—such as hatchling, flit, or setuptools—to handle your project’s packaging requirements.
Since the introduction of pyproject.toml, the build process has been decoupled from the underlying tools. You are no longer locked into legacy scripts; instead, you choose a backend that fits your project's complexity. Your selection is defined in the [build-system] table of your pyproject.toml file.
Choosing the Right Tool
The "best" backend depends on your specific needs:
- Flit: The minimalist choice. If you are building a pure-Python package and want simplicity without the overhead of complex configurations,
flit-coreis excellent. It focuses on modern, standardized packaging and has very little "cruft." - Hatchling: The modern all-rounder. As part of the
hatchproject,hatchlingis highly extensible. It is perfect if you want a balance between ease of use and advanced features, such as custom build hooks or sophisticated versioning strategies. - Setuptools: The industrial veteran. While it has been around for decades, its modern iterations are fully compliant with PEP 517. Choose this if you have complex C extensions, need deep integration with existing legacy build pipelines, or require highly intricate configuration that simpler tools might struggle with.
Implementation Example
To switch your backend, you simply update your pyproject.toml. For instance, to use hatchling, you would define it like this:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-awesome-package"
version = "0.1.0"
# Metadata is handled declaratively here
When evaluating these, consider your build time, the maturity of the plugin ecosystem you require, and how much "magic" you prefer. If you don't have C extensions or specialized build steps, start with flit or hatchling to keep your configuration clean and readable. You aren't choosing a language; you are choosing the engine that turns your source code into a distribution.
Key Takeaway: Choose a build backend based on your project's specific needs for simplicity (Flit), extensibility (Hatchling), or complex integration requirements (Setuptools).