Setuptools

82.0.1 · active · verified Fri Mar 27

Setuptools is Python's original and most established build backend for packaging, distributing, and installing Python packages, with full support for C/C++ extension modules, entry points, and PEP 517/660 editable installs. Current version is 82.0.1 (released Feb 2026). The project ships frequently — multiple major versions per month — and has a history of disruptive but well-warned breaking changes. Requires Python >=3.9 as of v75.4.0.

Warnings

breaking pkg_resources was fully removed in setuptools 81.0.0 (released Feb 8 2026). Any code or dependency doing 'import pkg_resources' will raise ModuleNotFoundError on setuptools >= 81.
Fix: Replace all pkg_resources usage with importlib.metadata (version, entry_points, etc.) and importlib.resources. For transitive dependencies you cannot control, pin 'setuptools<81' as a temporary workaround.
breaking setup.cfg keys using hyphens (e.g. 'description-file', 'long-description') raise InvalidConfigError in setuptools >= 78. This was a deprecation since 2021 that became an error in v78.
Fix: Replace all hyphenated keys in setup.cfg with their underscore equivalents (e.g. 'description_file', 'long_description'). The v78.0.1 reversal was itself reverted; the enforcement stands in current releases.
breaking project.license as a TOML table (e.g. license = {text = 'MIT'}) is deprecated as of setuptools 77 in favour of a plain SPDX string (license = 'MIT'). The table form will eventually be rejected.
Fix: Use a plain SPDX expression string: 'license = "MIT"' in pyproject.toml [project]. If you still need to support Python 3.8 builds (max setuptools 75.3.x), keep the table form and suppress the warning temporarily.
deprecated Running 'python setup.py install', 'python setup.py develop', 'python setup.py test', and other direct setup.py CLI invocations are deprecated and being removed incrementally. 'setup.py develop' now defers to pip internally.
Fix: Use 'pip install .' for installation, 'pip install -e .' for editable installs, 'python -m build' for building distributions, and a dedicated test runner (pytest) instead of 'setup.py test'.
breaking Python 3.8 support was dropped in setuptools 75.4.0. The last version supporting Python 3.8 is 75.3.x (actively maintained as a security-only branch).
Fix: If you must build on Python 3.8, pin 'setuptools<75.4' or use the 75.3.x maintenance branch. Otherwise upgrade to Python >=3.9.
gotcha Do NOT add 'wheel' to build-system.requires in pyproject.toml. This was historically recommended but is now unnecessary and actively discouraged by the official docs.
Fix: Use only 'requires = ["setuptools"]' in [build-system]. The build frontend (pip, build) handles wheel generation separately.
gotcha Static analysis tools (mypy, pyright, pylint) may not work correctly when setuptools uses an import-hook-based editable install (the default). This is a known limitation of the compat editable mode.
Fix: Pass '--config-settings editable_mode=compat' when running 'pip install -e .' to use a symlink/pth-file approach instead of the import hook.

Install

pip install setuptools Install latest
pip install "setuptools>=61.0" Install with pyproject.toml support (minimum recommended)

Imports

setup
```
from setuptools import setup
```
Used inside setup.py for legacy configuration; pyproject.toml is now preferred over a standalone setup.py
find_packages
```
from setuptools import find_packages
```
Discovers packages automatically; use find_namespace_packages() for PEP 420 namespace packages
find_namespace_packages
```
from setuptools import find_namespace_packages
```
Use instead of find_packages() when working with PEP 420 implicit namespace packages
Extension
```
from setuptools import Extension
```
distutils was removed from the stdlib in Python 3.12; always import Extension from setuptools
version (runtime metadata)
```
from importlib.metadata import version
```
pkg_resources was fully removed in setuptools 81.0.0 (Feb 2026); use importlib.metadata instead
entry_points (runtime)
```
from importlib.metadata import entry_points; eps = entry_points(group='my.group')
```
pkg_resources removed in setuptools 81; importlib.metadata is the stdlib replacement
build_meta (build backend)
```
build-backend = "setuptools.build_meta"  # in pyproject.toml [build-system]
```
Always declare this in pyproject.toml; pip assumes it as default only as a fallback for legacy projects

Quickstart

Minimal modern pyproject.toml-based package layout and programmatic setup.py usage. Run 'python -m build' from the project root to produce sdist + wheel in dist/.

# pyproject.toml (place in your project root — no setup.py needed)
# [build-system]
# requires = ["setuptools>=61"]
# build-backend = "setuptools.build_meta"
#
# [project]
# name = "mypackage"
# version = "0.1.0"
# description = "My package"
# requires-python = ">=3.9"
# license = "MIT"            # PEP 639 SPDX string (setuptools >= 77)
# dependencies = ["requests>=2.25"]
#
# [project.scripts]
# my-cli = "mypackage.cli:main"

# --- Programmatic use (setup.py, still valid as config file) ---
from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    python_requires=">=3.9",
    install_requires=["requests>=2.25"],
)

# --- Runtime metadata (replaces pkg_resources) ---
from importlib.metadata import version, entry_points

pkg_version = version("mypackage")
eps = entry_points(group="console_scripts")

view raw JSON →