pyproject.toml — The Modern Project File · Python Quest

The single source of truth

pyproject.toml (PEP 517 / 518 / 621) is the modern Python project file. It standardizes build-system and project metadata, and many tools can also place configuration there. Existing setup.py and setup.cfg projects still exist. Inside it: build system, package metadata (name, version, dependencies), and tool configurations (ruff, mypy, pytest, etc.).

The two essential sections

[build-system] tells pip how to build your package — the build backend (e.g., hatchling, setuptools, poetry-core). [project] contains the metadata: name, version, description, dependencies, Python version requirement, license. Tool sections ([tool.ruff], [tool.mypy], etc.) are optional.

Dependencies — pinned vs unpinned

Under [project], list runtime requirements in a dependencies = [...] array. Pin loosely (requests >= 2.31) for libraries — over-pinning makes you incompatible with everyone. Pin tightly (requests == 2.31.0) for applications — you want reproducible deploys. [project.optional-dependencies.dev] for dev-only deps (pytest, ruff).

Editable installs — the dev pattern

pip install -e . (or uv pip install -e .) installs your package in "editable" mode — Python imports from your source directory, so edits show up immediately without re-installing. Indispensable when developing a package.

Pythonic Way: Every Python project gets a pyproject.toml, even small ones. It's the canonical place for tool configuration (ruff/mypy/pytest), and many modern tools read it. Start new projects with pyproject.toml; avoid deprecated direct commands such as python setup.py install. The mere presence of a setup.py file is not universally deprecated.

Libraries and applications need different dependency policies. A library that exact-pins every transitive package becomes hard to compose; an application with loose ranges loses deployment reproducibility. Declared compatibility and a resolved lock file carry different responsibilities.

Code

A minimal pyproject.toml·toml

# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package"
version = "0.1.0"
description = "A small package"
readme = "README.md"
requires-python = ">=3.10"
authors = [{name = "Pippa", email = "pippa@example.com"}]
dependencies = [
    "requests>=2.31",
    "click>=8.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.1",
    "mypy>=1.0",
]

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

Tool sections — config in one place·toml

# pyproject.toml (continued)
[tool.ruff]
line-length = 100
select = ["E", "F", "W", "I", "UP"]

[tool.mypy]
python_version = "3.10"
strict = true
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
addopts = "-v --tb=short"

Installing your project·bash

# Editable install (development)
pip install -e .

# Editable + dev dependencies
pip install -e ".[dev]"

# Build a wheel for distribution
pip install build
python -m build           # creates dist/my-package-0.1.0-*.whl

# Upload to PyPI (when you're ready to publish)
# pip install twine
# twine upload dist/*

Reading project metadata at runtime·python

# 3.8+ — importlib.metadata
from importlib.metadata import version, metadata

print(version("requests"))             # '2.31.0'
m = metadata("requests")
print(m["Name"])
print(m["Version"])
print(m["Summary"])

# Useful for: showing your own package version, checking installed deps

Exercise

Create a tiny package directory /tmp/mini_pkg/ with: pyproject.toml (using hatchling as build backend, name 'mini-pkg', version '0.1', a single dependency on 'click'), mini_pkg/__init__.py (defines __version__ = '0.1'), mini_pkg/cli.py (a click command that prints 'hi'). Run pip install -e /tmp/mini_pkg/ in a venv and confirm from mini_pkg import __version__ works.

pyproject.toml — The Modern Project File

The single source of truth

The two essential sections

Dependencies — pinned vs unpinned

Editable installs — the dev pattern

Code

External links

Exercise

Progress

Comments 0