Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 38 ยท pyproject and Metadata

pyproject.toml Basics

Learn the structure of pyproject.toml, its three standard tables, TOML syntax and how to read and validate one with tomllib, step by step with live code.

pyproject.toml is the single configuration file at the root of a modern Python project. It answers three questions in three standard places: how do I build this project ([build-system]), what is this project ([project]), and how should my tools behave ([tool.*]). Before it existed, you scattered this across setup.py, setup.cfg, MANIFEST.in, requirements.txt, tox.ini, .flake8 and more. Today one file does the job, and every major tool reads it.

The file is written in TOML, a small configuration format built for humans. Python 3.11+ includes a parser, tomllib, so we can read real files in the live editors below.

TOML in five minutes

TOML
# comments start with a hash
title = "demo"                  # string
count = 3                       # integer
ratio = 0.5                     # float
enabled = true                  # boolean (lowercase)
names = ["a", "b", "c"]         # array

[table]                         # a section: becomes a dictionary
key = "value"

[table.sub]                     # nested table
x = 1

[[items]]                       # array of tables: a list of dictionaries
id = 1
[[items]]
id = 2

Rules to remember: strings need quotes (basic "..." with escapes, literal '...' without), keys are unquoted unless they have spaces or dots, and indentation does not matter. Dotted keys such as tool.black.line-length = 100 are shorthand for nested tables.

Python TOML becomes a Python dictionary

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

tomllib only reads TOML. To write it, install a library such as tomli-w (small and standard-like), or edit files with a tool that preserves comments (tomlkit), which is what uv add and Poetry do.

The three standard tables

TOML
[build-system]
requires = ["hatchling>=1.25"]
build-backend = "hatchling.build"

[project]
name = "weather-cli"
version = "0.3.0"
description = "Print the forecast in your terminal"
requires-python = ">=3.10"
dependencies = ["requests>=2.30", "rich>=13"]

[tool.ruff]
line-length = 100
  • [build-system] (PEP 517 and 518) tells a frontend what to install to build the project, and which backend to call. It is the only table pip needs to build.
  • [project] (PEP 621) holds the standard metadata: name, version, dependencies, authors, license, URLs, entry points. Every backend understands it.
  • [tool.<name>] belongs to a specific tool. tool.ruff, tool.pytest.ini_options, tool.mypy, tool.hatch, tool.uv and so on. Tools ignore tables that are not theirs, so many can coexist.
flowchart TD
    F["pyproject.toml"] --> B["[build-system]<br/>how to build"]
    F --> P["[project]<br/>what it is"]
    F --> T["[tool.*]<br/>how tools behave"]
    B --> BB["pip / build / uv build"]
    P --> BB
    T --> TT["ruff, pytest, mypy, hatch, uv..."]

Build frontends read the first two tables; each tool reads only its own [tool.x] table.

What if [build-system] is missing?

If a project has no [build-system], pip assumes the legacy default (setuptools with wheel, as if there were a setup.py). That fallback exists for old projects. In a new project, always declare it explicitly so builds are reproducible and the backend version is visible.

Reading a real file

Python Inspect the three tables of a project file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Validating it

A frontend checks three things: the file parses, [build-system] has requires (a list) and build-backend (a string), and [project] follows PEP 621. In particular name is required, and version must either appear or be listed in dynamic. Writing your own small validator makes the rules concrete.

Python A minimal pyproject validator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real validators (such as validate-pyproject, which many backends run for you) do the same and much more, checking every field against the PEP 621 schema.

Common tool tables

You will configure many tools in the same file over the course of this tutorial. Here is a small preview so the pattern becomes familiar:

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

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

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

[tool.mypy]
strict = true

[tool.coverage.run]
branch = true

Name collisions are impossible by design: PEP 518 reserves [tool] for tools, and each tool picks a name under it (usually its own name). Third-party tables outside [tool], [project] and [build-system] should not be invented.

Where do the other files go?

Old file Today
setup.py / setup.cfg [project] + [build-system] (a setup.py is only needed for custom builds)
MANIFEST.in Backend config, e.g. [tool.hatch.build] or [tool.setuptools]
requirements.txt Still used for pinned installs; abstract dependencies belong in [project]
tox.ini, pytest.ini, .coveragerc, mypy.ini [tool.*] tables (still honored if they exist)
.flake8, .pylintrc, black config [tool.ruff], [tool.black], ...

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which table tells pip which backend to use to build the project?

    [build-system] lists the requirements to install and the build-backend to call (PEP 517/518).
  2. 2. Which Python module (3.11+) reads TOML?

    tomllib is in the standard library and read-only. Use tomli-w or tomlkit to write.
  3. 3. What does the [tool.ruff] table represent?

    Each tool owns its own [tool.<name>] table.
  4. 4. Which two fields are essential in [project] unless made dynamic?

    PEP 621 requires name; version is required unless listed in dynamic.

Summary

  • pyproject.toml replaces setup.py, setup.cfg, and scattered tool configs.
  • Three standard places: [build-system], [project], [tool.*].
  • TOML has strings, numbers, booleans, arrays, tables and arrays of tables; tomllib parses it.
  • Always declare [build-system] explicitly in new projects.
  • [project] needs name and either version or a dynamic entry.
  • Each tool reads only its own [tool.<name>] table.

Next: Project Metadata Fields