Skip to content

setuptools: Python Package Build Backend

by Tim Hopper
Packaging

Setuptools is Python’s original and most established build backend, providing tools for building, distributing, and installing Python packages. It serves as the foundation for much of Python’s packaging ecosystem and supports a wide range of packaging use cases.

For many years, setuptools was the de facto standard for building Python packages. However, in recent years, language-level support was introduced for other packaging tools (e.g. Poetry and Hatch) , and setuptools-based workflows have become less popular.

Note

For new projects without C extensions or legacy constraints, hatch or uv provide simpler workflows. Setuptools remains the right choice for packages with C extensions or complex build requirements.

Core Features

Build System

  • Package Creation: Builds both source distributions (sdists) and wheel distributions
  • Extension Module Support: Handles compilation of C extensions and Cython code
  • Entry Points: Manages console scripts and plugin registration
  • Resource Management: Handles package data files and non-code resources
  • Command Customization: Supports custom build steps and commands

Configuration Options

In the past, setuptools projects required a setup.py script to be present in the project root. However, this is no longer the case. setuptools configurations can be defined in pyproject.toml.

Setuptools can be configured through pyproject.toml or the legacy setup.py file:

# Modern configuration (pyproject.toml)
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "example"
version = "0.1.0"
description = "Example package"
requires-python = ">=3.8"
dependencies = ["requests>=2.25.0"]
# Legacy configuration (setup.py)
from setuptools import setup

setup(
    name="example",
    version="0.1.0",
    description="Example package",
    python_requires=">=3.8",
    install_requires=["requests>=2.25.0"],
)

Using setuptools as a build backend with uv

To create a new uv project that uses setuptools as its build backend:

uv init --build-backend setuptools my-lib

Setuptools is the right backend choice when a package includes C extensions, Cython code, or other compiled components that newer backends like uv_build and hatchling don’t handle.

Building with Setuptools 

# Build distributions
python -m build

# Or with uv
uv build

Both commands invoke setuptools as the build backend when pyproject.toml declares setuptools.build_meta in the [build-system] table.

Advantages

  • Well-established with decades of development and broad platform support
  • Handles complex packaging scenarios including C extensions and custom build steps
  • Compatible with modern Python packaging standards (PEP 621)
  • Comprehensive documentation available

Limitations

  • Legacy API carries historical design choices that can be confusing
  • No built-in dependency locking; requires additional tools for lockfiles
  • Less frequent updates and slower development cycle than newer alternatives
  • More configuration options create a steeper learning curve

Learn More

Last updated on
setup.cfgtox

Please submit corrections and feedback...