Course contentsShow
← Python
Lesson 524 of 1,0608. Professional Tooling and PackagingFree lesson

Declaring Build-Time Dependencies with PEP 518

Master the use of the build-system table to isolate and specify the tools required to build your project before installation.

In this lesson, you will learn how to use the [build-system] table in your pyproject.toml to explicitly declare the tools required to build your project before the installation process even begins.

The Problem: The "Chicken and Egg" Dilemma

Historically, Python packaging relied on setup.py scripts to define dependencies. However, if your project required a specific library just to run the build process (like setuptools, wheel, or specialized tools like cython), you faced a "chicken and egg" problem: the build tool couldn't install the build dependencies because it needed them to start.

The PEP 518 Solution

PEP 518 introduced the [build-system] table in pyproject.toml. This standardizes a way to tell frontend tools (like pip, build, or uv) exactly what packages are needed to prepare your project for installation. These packages are installed into an isolated, temporary environment by the build frontend before the build backend is invoked.

Here is how you define it:

[build-system]
# The tools required to actually execute the build
requires = ["setuptools>=61.0", "wheel"]

# The backend that coordinates the build process
build-backend = "setuptools.build_meta"

Why This Matters

By declaring your requirements here, you ensure your project is reproducible across different machines. If your project depends on cython to compile C extensions, listing it in requires ensures that anyone—or any CI system—that attempts to install your project will have a working cython environment automatically prepared. It separates what your application needs to run (defined in [project.dependencies]) from what your project needs to be built (defined in [build-system]).

By keeping these build-time dependencies isolated, you avoid polluting your main environment with tools that are only necessary during the packaging phase, keeping your final installation lean and predictable.

Key Takeaway: Use the [build-system] table in pyproject.toml to declare tools needed to build your project, ensuring isolated and deterministic package creation every time.