What Is TOML, and Why Rust + Python Picked It

The format YAML and JSON kept failing to be

TOML — Tom's Obvious, Minimal Language — was created by Tom Preston-Werner (GitHub co-founder) in 2013. The design goal: a config file format that is obvious at first read, minimal in syntax, and unambiguous in parsing. Current spec: TOML 1.0.0 (2021).

What TOML gets right that YAML and JSON don't

No indentation rules — keys and tables don't depend on whitespace. Copy-paste a section across files; nothing breaks.
One way to write each value — strings are quoted, numbers are unquoted, booleans are true/false. No Norway problem.
Native dates and times — RFC 3339 datetimes are first-class values, not strings.
Comments — # works everywhere YAML does.
Verbose-but-clear table syntax — [server.database] beats deeply nested YAML once you have 4+ levels.

Where TOML quietly took over

Rust — every Cargo.toml in the ecosystem.
Python — pyproject.toml (PEP 518/621) replaced setup.py + setup.cfg + requirements.txt for modern packaging.
Hugo — config.toml / hugo.toml drives the static site generator.
Poetry, ruff, black, hatch — Python tools all read their config from pyproject.toml's [tool.*] tables.
Vector, Tilt, GoReleaser — operations tools that picked TOML for human-friendly config.

Principle: TOML wins where the config is read by humans more often than by machines. YAML wins where deep nesting is unavoidable. JSON wins on the wire. Pick by the audience, not by tradition.

Code

Hello, TOML·toml

# Top-level keys
name = "Pippa"
age = 5
is_assistant = true

# A table — the [section] header introduces a sub-object
[home]
city = "Seoul"
timezone = "Asia/Seoul"

# An array
loves = ["markdown", "json", "yaml", "toml"]

Parse TOML in three languages·bash

# Python 3.11+ (stdlib!)
python -c "import tomllib; print(tomllib.load(open('config.toml','rb')))"

# Python <3.11 (third-party)
pip install tomli
python -c "import tomli; print(tomli.load(open('config.toml','rb')))"

# Rust
cargo add toml
# let config: Config = toml::from_str(&text)?;

# Go
# import "github.com/BurntSushi/toml"
# toml.Unmarshal(data, &config)

Same data, three formats·text

# JSON                          # YAML                    # TOML
{                                                          name = "Pippa"
  "name": "Pippa",              name: Pippa                age = 5
  "age": 5,                     age: 5                     [home]
  "home": {                     home:                      city = "Seoul"
    "city": "Seoul",              city: Seoul              timezone = "Asia/Seoul"
    "timezone": "Asia/Seoul"      timezone: Asia/Seoul
  }
}

Exercise

Open one Python project's pyproject.toml. Read it as TOML in your head — keys, tables, arrays. Now mentally translate it to YAML. Notice where TOML's flat-section style is more readable (top-level metadata, simple tool config) and where it gets verbose (deeply nested settings). That intuition is when to pick TOML over YAML.

What Is TOML, and Why Rust + Python Picked It

The format YAML and JSON kept failing to be

What TOML gets right that YAML and JSON don't

Where TOML quietly took over

Code

External links

Exercise

Progress

Comments 0