Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python tomllib: Read pyproject.toml Files

Read pyproject.toml with Python's tomllib: TOML loading, nested data, error handling, and tomli on older Python versions.

~4 min readPython
#tomllib#pyproject.toml#TOML parsing#configuration files
Illustration of a Python script reading a pyproject.toml file using the tomllib module

pyproject.toml is the standard configuration file for Python packaging and project metadata. Python 3.11's tomllib module provides a built-in, dependency-free way to parse it, so tooling, scripts, and build automation can read project configuration without third-party packages. This article shows how to load pyproject.toml with tomllib, work with the resulting data structures, handle errors, and support older Python versions with the tomli backport.

Why tomllib Matters for pyproject.toml

Before Python 3.11, parsing TOML required third-party libraries like tomli or toml. Now tomllib is part of the standard library, so you can read pyproject.toml without adding dependencies. This is especially useful for small utilities, CI scripts, or any code that needs to inspect project configuration without pulling in a package manager.

tomllib parses TOML into native Python dictionaries, lists, strings, integers, floats, booleans, and date/time values. The structure of a pyproject.toml file maps directly to nested dictionaries and lists, making it straightforward to access fields like project.name, project.version, or build-system.requires.

Basic Usage: Reading a pyproject.toml File

The core function is tomllib.load(), which takes a binary file object. This is important: tomllib.load() expects bytes, not text. The most common pattern is to open the file in binary mode and pass it directly.

python
import tomllib with open("pyproject.toml", "rb") as f: data = tomllib.load(f) print(data["project"]["name"])

If you already have the TOML content as a string, use tomllib.loads() instead:

python
import tomllib toml_str = """ [project] name = "example" version = "1.0.0" """ data = tomllib.loads(toml_str) print(data["project"]["version"])

Both functions return a dict with the same structure as the TOML file. The binary mode requirement exists because TOML is specified as UTF-8, and tomllib handles encoding internally.

Handling TOML Data Types and Nested Structures

TOML supports tables (sections), arrays, inline tables, and scalar types. tomllib converts them to Python types: tables become dict, arrays become list, and scalars map to str, int, float, bool, and datetime.date, datetime.time, or datetime.datetime for TOML date/time values.

Consider this pyproject.toml snippet:

toml
[project] name = "demo" dependencies = ["requests>=2.28", "click"] [project.optional-dependencies] test = ["pytest"] [tool.black] line-length = 88

Accessing nested data requires chaining dictionary keys:

python
import tomllib with open("pyproject.toml", "rb") as f: data = tomllib.load(f) name = data["project"]["name"] deps = data["project"]["dependencies"] line_length = data["tool"]["black"]["line-length"]

Note that TOML keys with hyphens (like line-length) are accessed using the string key, not attribute access. The returned dictionary preserves the exact key names from the file.

Arrays of tables are also common in pyproject.toml, for example in [[tool.poetry.source]] or [[tool.mypy.overrides]]. These become lists of dictionaries, which you can iterate over.

Error Handling: When the File Is Invalid or Missing

tomllib raises tomllib.TOMLDecodeError if the file contains invalid TOML syntax. This is a subclass of ValueError, so you can catch it specifically or more broadly.

python
import tomllib try: with open("pyproject.toml", "rb") as f: data = tomllib.load(f) except FileNotFoundError: print("pyproject.toml not found") except tomllib.TOMLDecodeError as e: print(f"Invalid TOML: {e}")

A common mistake is to open the file in text mode ("r") instead of binary mode ("rb"). The documented API expects a binary file object. If you already have a text stream or a string, call tomllib.loads() with the string content instead.

Another edge case: pyproject.toml may not exist when you run a script from a subdirectory. Always check the path or catch FileNotFoundError if the file is optional.

Reading pyproject.toml in Different Python Versions

tomllib is only available in Python 3.11 and later. If your code must run on Python 3.10 or earlier, you can use the tomli backport, which has the same API. A common pattern is to try importing tomllib and fall back to tomli:

python
try: import tomllib except ModuleNotFoundError: import tomli as tomllib

This lets you write code that works across Python versions. The backport tomli is a drop-in replacement for reading TOML; it does not support writing, just like tomllib.

When you control the runtime environment, you can simply require Python 3.11+ and use tomllib directly. For libraries that need broader compatibility, the fallback approach is standard.

Practical Patterns for Accessing Project Metadata

A common use case is reading the project name and version to display or validate it. Since pyproject.toml follows the PEP 621 specification, the [project] table contains standardized fields.

python
import tomllib def get_project_version(path="pyproject.toml"): with open(path, "rb") as f: data = tomllib.load(f) return data.get("project", {}).get("version")

Using .get() with defaults prevents KeyError when fields are missing. This is useful when you want to gracefully handle incomplete configuration files.

Another pattern is to combine tomllib with pathlib for cleaner path handling:

python
from pathlib import Path import tomllib pyproject = Path("pyproject.toml") if pyproject.exists(): with pyproject.open("rb") as f: data = tomllib.load(f)

This avoids manual string concatenation and makes the code more portable.

Common Pitfalls When Using tomllib

One frequent mistake is expecting tomllib.load() to accept a file path as a string. It does not; it requires a file object. Always use open() or Path.open().

Another pitfall is assuming that TOML keys are case-insensitive or that hyphens are converted to underscores. Neither is true. tomllib preserves keys exactly as written. If you need to access a key with a hyphen, use the exact string.

Also, be aware that tomllib does not support writing TOML. It is a read-only parser. If you need to modify and write back a pyproject.toml, you'll need a library like tomlkit or tomli-w. This is a deliberate design choice; the standard library only handles parsing.

Finally, remember that tomllib loads the entire file into memory. For typical pyproject.toml files this is negligible. If you are processing many large TOML files in a loop, be aware that each load() call reads the whole file and stores the parsed data, so avoid retaining parsed results you do not need and limit file sizes where practical.

When you need to read pyproject.toml in a Python script, tomllib gives you a clean, dependency-free way to access project configuration. Its strict TOML compliance and native type mapping make it the right choice for modern Python tooling.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.