pyproject-toml

Configure Everything in pyproject.toml

pyproject.toml is the single source of truth for a Python package: build system, metadata, dependencies, and tool configuration. As of pip 24.0, setup.py install is no longer supported. Every major package -- Pydantic, httpx, Flask, pytest, attrs, Ruff -- has migrated. There is no reason to use setup.py, setup.cfg, or requirements.txt as primary configuration for any new package.

Anatomy: The Four Sections

Every pyproject.toml contains four logical sections. Keep them in this order:

1. [build-system] -- declares the build backend (PEP 517/518)
2. [project] -- standardized metadata (PEP 621)
3. [dependency-groups] -- dev-only dependencies (PEP 735)
4. [tool.*] -- tool-specific configuration (pytest, mypy, ruff, coverage)

Build Backend Selection

Use hatchling for new pure-Python packages. It is PyPA-maintained, fast, extensible, and the default for hatch new and uv init --lib.

Your Package	Use This Backend	Declaration
Pure Python (new)	hatchling	requires = ["hatchling"]
Pure Python (very simple)	flit-core	requires = ["flit_core>=3.10,<4"]
Pure Python (legacy)	setuptools	requires = ["setuptools>=75.0"]
Rust extensions (PyO3)	maturin	requires = ["maturin>=1.7,<2.0"]
C/C++ with CMake	scikit-build-core	requires = ["scikit-build-core>=0.10"]

What top packages use:

Package	Backend	Reason
Pydantic, httpx, Black, attrs	hatchling	Modern, clean, PyPA-aligned
Flask, Jinja2, Werkzeug	flit-core	Simple, minimal needs
pytest	setuptools	Historical, complex build
Polars, Ruff, pydantic-core	maturin	Rust (PyO3) bindings

PEP 621: Project Metadata

Only name and version are strictly required (unless version is listed in dynamic). For any public package, always set these recommended fields:

Field	Purpose	Example
name	PyPI distribution name (kebab-case)	"my-library"
version	PEP 440 version (or list in dynamic)	"1.0.0"
description	Single-line summary	"A fast HTTP client"
readme	PyPI long description	"README.md"
license	PEP 639 SPDX expression	"MIT"
requires-python	Minimum supported Python	">=3.10"
authors	Author list	[{ name = "Jane Doe" }]
classifiers	Trove classifiers (include Typing :: Typed)	See Reference Configuration
dependencies	Runtime dependencies (lower bounds only)	["httpx>=0.27"]

Set [project.urls] with at minimum Repository and Changelog -- PyPI renders recognized keys (Documentation, Issues, Funding) with icons. See the Reference Configuration for a complete example.

PEP 639: SPDX License Expressions

Use a plain SPDX string, not the legacy table form. All modern build backends and PyPI support this since 2024.

Do	Do Not
license = "MIT"	license = { text = "MIT License" }
license = "Apache-2.0"	license = { file = "LICENSE" }
license = "MIT OR Apache-2.0"	license = "BSD" (ambiguous -- which BSD?)

PEP 735: Dependency Groups

Use [dependency-groups] for dev-only dependencies. These are not published to PyPI and cannot be installed by end users.

[project.optional-dependencies]          # Published to PyPI -- user-facing feature variants
postgres = ["asyncpg>=0.29"]

[dependency-groups]                      # NOT published -- developer-only
test = ["pytest>=8.0", "pytest-cov>=6.0", "coverage[toml]>=7.6"]
lint = ["ruff>=0.9", "mypy>=1.14", "pyright>=1.1"]
dev = [{ include-group = "test" }, { include-group = "lint" }, "pre-commit>=4.0"]

User-facing feature variants (postgres, redis, HTTP/2) go in [project.optional-dependencies]. Dev-only tools (test, lint, docs) go in [dependency-groups]. Groups support { include-group = "name" } for composition. Install with uv sync --group dev or pip install --dependency-group test.

Dynamic Versioning

Derive the version from git tags to maintain a single source of truth. No version strings to update manually.

[project]
dynamic = ["version"]

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/my_library/_version.py"

Release workflow: git tag v1.2.3 && git push --tags -- CI handles the rest.

Runtime access -- import from the generated _version.py (see project-structure skill for rationale):

from my_library._version import __version__, __version_tuple__

For projects preferring explicit control, a static version in pyproject.toml (version = "1.2.3") is valid for small or internal packages.

Dependency Version Constraints

Use lower bounds only for libraries. Reflexive upper bounds create ecosystem-wide resolution conflicts.

Situation	Pattern	Example
Default (libraries)	Lower bound only	httpx>=0.27
Tightly coupled (same team)	Exact or ==N.*	httpcore==1.*
Known breakage at next major	Upper bound	legacy-lib>=1.0,<2.0
Patch-level compatibility	Compatible release	some-api~=3.2.0
Applications	Lock file	uv.lock (not pinned in pyproject.toml)

Conditional dependencies for platform or Python version differences:

dependencies = [
    "tomli>=2.0; python_version < '3.11'",
    "colorama>=0.4; sys_platform == 'win32'",
]

Entry Points and Console Scripts

Register CLI commands via [project.scripts]:

[project.scripts]
my-cli = "my_library.cli:main"

Register plugin entry points for discovery via importlib.metadata:

[project.entry-points."myframework.plugins"]
my-plugin = "my_plugin_package:PluginClass"

Tool Configuration Consolidation

Consolidate all tool settings into [tool.*] sections of pyproject.toml where the tool supports it. Do not create .flake8, mypy.ini, pytest.ini, or .coveragerc -- Ruff, mypy, pytest, and coverage all read from pyproject.toml natively. Ruff replaces flake8, isort, Black, and pyupgrade as a single tool.

Exceptions: Tools that do not support pyproject.toml configuration keep their own files. The most common exception is .pre-commit-config.yaml -- pre-commit is a polyglot tool managing hooks across languages and requires its own YAML format.

The Reference Configuration below shows all recommended [tool.*] sections.

Reference Configuration

A complete, production-ready pyproject.toml for a new pure-Python package:

[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
name = "my-library"
dynamic = ["version"]
description = "A well-packaged modern Python library"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
authors = [{ name = "Jane Doe", email = "jane@example.com" }]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Typing :: Typed",
]
dependencies = ["httpx>=0.27", "pydantic>=2.0"]

[project.urls]
Repository = "https://github.com/org/my-library"
Changelog = "https://github.com/org/my-library/blob/main/CHANGELOG.md"

[project.scripts]
my-cli = "my_library.cli:main"

[dependency-groups]
test = ["pytest>=8.0", "pytest-cov>=6.0", "coverage[toml]>=7.6"]
lint = ["ruff>=0.9", "mypy>=1.14", "pyright>=1.1"]
docs = [
    "mkdocs-material>=9.5",
    "mkdocstrings[python]>=0.27",
    "mkdocs-gen-files>=0.5",
    "mkdocs-literate-nav>=0.6",
    "mkdocs-section-index>=0.3",
    "mike>=2.1",
]
dev = [{ include-group = "test" }, { include-group = "lint" }, { include-group = "docs" }, "pre-commit>=4.0"]

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/my_library/_version.py"

[tool.hatch.build.targets.wheel]
packages = ["src/my_library"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = ["--strict-markers", "--strict-config", "-ra"]
xfail_strict = true
filterwarnings = ["error"]
asyncio_mode = "auto"

[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_configs = true
enable_error_code = ["ignore-without-code", "redundant-cast", "truthy-bool"]

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

[tool.pyright]
pythonVersion = "3.10"
typeCheckingMode = "standard"
reportUnnecessaryTypeIgnoreComment = true
enableTypeIgnoreComments = false

[tool.ruff]
target-version = "py310"
line-length = 88
src = ["src"]

[tool.ruff.lint]
select = ["F", "E", "W", "I", "N", "UP", "B", "SIM", "C4", "RUF", "PERF", "TCH", "C90"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "PLR2004"]
"__init__.py" = ["F401"]

[tool.ruff.lint.isort]
known-first-party = ["my_library"]

[tool.ruff.lint.mccabe]
max-complexity = 10

[tool.ruff.format]
docstring-code-format = true

[tool.coverage.run]
source_pkgs = ["my_library"]
branch = true
parallel = true

[tool.coverage.report]
show_missing = true
fail_under = 85
exclude_also = ["if TYPE_CHECKING:", "@overload", "raise NotImplementedError", "\\.\\.\\."]

Review Checklist

When reviewing pyproject.toml configuration:

• [build-system] declares a PEP 517 backend (hatchling, flit-core, setuptools, or maturin)
• [project] uses PEP 621 metadata, not [tool.setuptools] for name/version/dependencies
• license uses PEP 639 SPDX string format ("MIT"), not legacy table form
• requires-python is set to the minimum supported Python version
• readme, description, authors, and classifiers are populated
• Runtime dependencies use lower bounds only (>=), no reflexive upper bounds
• Dev dependencies use [dependency-groups] (PEP 735), not [project.optional-dependencies]
• [project.optional-dependencies] is reserved for user-facing feature variants only
• Version is either static or dynamic via hatch-vcs/setuptools-scm -- not duplicated across files
• All tool config (pytest, mypy, ruff, coverage) lives in [tool.*] sections, not separate files
• [project.urls] includes at least Repository and Changelog
• No setup.py, setup.cfg, requirements.txt, .flake8, mypy.ini, or pytest.ini exist
• Console scripts use [project.scripts], not setuptools console_scripts entry point syntax