pyproject.toml: Python Project Configuration File

The pyproject.toml file is the standard configuration file for modern Python projects, defined by PEP 518. It serves as a central place to specify project metadata, dependencies, build requirements, and tool configurations.

Key Aspects

• Single Source: Consolidates project configuration that was historically spread across multiple files like setup.py, setup.cfg, and requirements.txt
• Standards Compliant: Follows modern Python packaging standards (PEP 517/518/621)
• Tool Agnostic: Works with any compliant build backend or package manager
• TOML Format: Uses TOML for improved readability and reduced syntax errors compared to JSON or INI formats

Core Sections Examples

Project Metadata (PEP 621)

[project]
name = "example"
version = "0.1.0"
description = "A example project"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
    "pandas~=2.0.0",
]

Optional Dependencies

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff"]
docs = ["sphinx", "furo"]

Optional dependency groups allow users to install subsets of extras with pip install example[dev] or uv pip install example[docs].

Build System (PEP 517)

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Tool Configuration

The [tool.*] namespace is reserved for third-party tools to store their configuration. Each tool claims its own sub-table. This eliminates the need for separate config files like .flake8, mypy.ini, or pytest.ini.

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

[tool.ruff.lint]
select = ["E", "F", "I"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q"

[tool.mypy]
strict = true
warn_return_any = true

[tool.uv]
dev-dependencies = ["pytest>=7.0.0", "ruff"]

Important Fields

[project]

• name: Package name on PyPI
• version: Package version
• description: Short project summary
• requires-python: Python version constraints
• dependencies: Runtime package requirements
• optional-dependencies: Feature-specific packages

[build-system]

• requires: Build system dependencies
• build-backend: Backend package name
• backend-path: Custom backend location

Learn More

• How to migrate from requirements.txt to pyproject.toml with uv
• Why should I choose pyproject.toml over requirements.txt?
• What is PEP 621 compatibility?
• What is PEP 517/518 compatibility?
• Python Packaging User Guide
• PEP 518 - Build System Requirements
• PEP 621 - Project Metadata
• TOML Documentation
• uv - Fast package manager that scaffolds and manages pyproject.toml
• Build backends: Setuptools, Hatch, Flit