setuptools: Python Package Build Backend

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.

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

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

• pyproject.toml
• Setuptools Documentation
• PEP 621 Support
• Packaging Python Projects Guide
• Setuptools with pyproject.toml Example
• Setuptools with setup.py Example