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

Transitioning from setup.py to pyproject.toml

Understand the historical shift toward declarative configuration and why pyproject.toml is now the mandatory standard for Python projects.

In this lesson, you will learn why the Python ecosystem has moved away from imperative setup.py files toward the declarative pyproject.toml standard.

The Problem with Imperative Configuration

For many years, setup.py was the heart of every Python project. It was essentially a Python script that executed code to configure your package. While powerful, this created a major security and reliability problem: to figure out the metadata of a package (like its version or dependencies), the packaging tool had to run the script.

Executing arbitrary code during installation is slow, requires a runtime environment, and poses security risks. If your setup.py had a bug, the installation would fail. It was an imperative "how-to" approach rather than a declarative "what-is" approach.

The Declarative Shift

pyproject.toml changes this by using a static, declarative format. Instead of writing Python code, you define your project’s identity and requirements using a standard configuration language called TOML.

When you move your configuration from setup.py to pyproject.toml, you are separating your build-time instructions from your application logic. A tool can now read your project configuration without executing a single line of your code.

Compare the old way to the new way:

The old way (setup.py):

from setuptools import setup
setup(name="my_package", version="1.0.0")

The new way (pyproject.toml):

[project]
name = "my_package"
version = "1.0.0"

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

Why This Matters

By standardizing on pyproject.toml (defined in PEP 517 and 518), the Python packaging ecosystem has achieved interoperability. It doesn’t matter if you use pip, uv, or poetry—they all understand the same pyproject.toml structure. This transition turns packaging from a "black box" script execution into a predictable, fast, and secure configuration check. It allows tools to optimize the build process because they know exactly what you need before the installation even starts.

Key Takeaway: Moving to pyproject.toml replaces dangerous, slow, imperative scripts with a safe, static, and tool-agnostic configuration that is now the mandatory standard for modern Python packaging.