pyproject.toml
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
, andrequirements.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",
]
Build System (PEP 517)
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
Tool Configuration
[tool.uv]
dependencies = ["pytest>=7.0.0"]
[tool.ruff]
line-length = 88
Important Fields
name
: Package name on PyPIversion
: Package versiondescription
: Short project summaryrequires-python
: Python version constraints
dependencies
: Runtime package requirementsoptional-dependencies
: Feature-specific packages[tool.uv.dependencies]
: Development dependencies
requires
: Build system dependenciesbuild-backend
: Backend package namebackend-path
: Custom backend location
Learn More
- Python Packaging User Guide
- PEP 518 - Build System Requirements
- PEP 621 - Project Metadata
- TOML Documentation
Also Mentioned In
- Black
- build
- Create your first Python project
- Does Poetry Support Python Standards for Dependency Management?
- Flit
- How to Fix ModuleNotFoundError: No module named 'numpy' During pip Install
- How to fix Python version incompatibility errors in uv
- How to migrate from requirements.txt to pyproject.toml with uv
- How to Run a Python REPL with uv
- How to sort Python imports with Ruff
- PDM
- poetry
- pylint
- ruff
- Set up Ruff for formatting and checking your code
- setuptools
- What are Optional Dependencies and Dependency Groups?
- What is a build backend?
- What is a PEP?
- What is PEP 517/518 compatability?
- What is PEP 621 compatability?
- What is PEP 735?
- Why should I avoid using the system Python?
- Why Should I Choose pyproject.toml over requirements.txt for managing dependencies?
Last updated on