Python TOML Configuration — ELI5

Imagine you’re writing down the settings for a video game.

You want it to be clear enough that anyone can read it and change things without breaking the game:

[player]
name = "Alex"
lives = 3
difficulty = "hard"

[graphics]
resolution = "1920x1080"
fullscreen = true

That’s TOML — Tom’s Obvious Minimal Language.

It was designed to be the simplest possible configuration format. Every setting is a key = value pair. Groups of settings go under [section] headers. That’s basically it.

Why TOML was created:

People got tired of YAML’s surprising gotchas (like “NO” becoming false) and JSON’s lack of comments. TOML was built to be:

• Obviously readable
• Hard to get wrong
• Supportive of comments
• Strict enough to prevent accidental mistakes

Where you see TOML:

• pyproject.toml — Python’s own project configuration file
• Cargo.toml — Rust’s package manager
• Hugo and other static site generators
• Many modern tool configurations

Python and TOML:

Since Python 3.11, TOML reading is built right into the standard library with the tomllib module. No extra installation needed.

import tomllib

with open("config.toml", "rb") as f:
    config = tomllib.load(f)

The one limitation:

Python’s built-in tomllib can only read TOML, not write it. For writing, you need the third-party tomli-w or tomlkit package.

One Thing to Remember

TOML is the config format designed to be impossible to misread — Python adopted it for pyproject.toml and added built-in support because it’s the safest choice for configuration files.