Skip to content

setuptools: Python Package Build Backend

by Tim Hopper · Markdown
Packaging

Setuptools is the original Python build backend. Created in 2004 as an extension of distutils, it handles building source distributions (sdists), wheels, C extensions, and entry points.

When to use setuptools

Setuptools is the right choice for packages with C extensions, Cython code, or other compiled components that newer backends like hatchling and uv_build do not handle. For pure-Python packages without legacy constraints, hatch or uv provide simpler workflows.

Key Features

  • Builds both sdists and wheels
  • Compiles C extensions and Cython code
  • Manages console scripts and plugin registration via entry points
  • Handles package data files and non-code resources
  • Supports custom build steps and commands

Configuration

Setuptools projects define configuration in pyproject.toml. The legacy setup.py file is still supported but no longer required.

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.10"
dependencies = ["requests>=2.28.0"]

The legacy equivalent uses a setup.py script:

setup.py
from setuptools import setup

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

Using setuptools with uv

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

uv init --build-backend setuptools my-lib

To build distributions:

uv build

Both uv build and python -m build invoke setuptools when pyproject.toml declares setuptools.build_meta in the [build-system] table.

Pros

  • Handles complex packaging scenarios including C extensions and custom build steps
  • Compatible with modern Python packaging standards (PEP 621)
  • Decades of development with broad platform support

Cons

  • Legacy API carries historical design choices that can be confusing
  • No built-in dependency locking; requires additional tools for lockfiles
  • More configuration options than newer backends, creating a steeper learning curve

Learn More

Last updated on
setup.cfgSphinx