What is TOML? Complete Guide with Examples
TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to be easy to read due to its obvious semantics. Created by Tom Preston-Werner (GitHub co-founder), TOML uses INI-inspired key-value pairs with explicit data types (strings, integers, floats, booleans, dates, arrays, tables). It's the standard configuration format for Rust (Cargo.toml), Python packaging (pyproject.toml), and Hugo static sites.
How Does TOML Work?
TOML files use key = value pairs grouped into sections called tables (denoted by [table-name] headers). Unlike YAML, TOML doesn't rely on indentation — structure comes from table headers and dotted keys (server.host = 'localhost'). TOML has explicit types: strings are always quoted, integers and floats are unquoted numbers, booleans are true/false, and dates use RFC 3339 format. Array of tables ([[array-table]]) represent lists of objects. The format is designed to map unambiguously to a hash table.
Key Features
- INI-style sections ([table]) with nested sub-tables via dotted headers ([server.database])
- Explicit typing — no YAML-style type ambiguity (Norway problem where 'NO' becomes false)
- First-class date/time support using RFC 3339 format (2024-01-15T09:30:00Z)
- Multi-line basic strings (triple quotes) and literal strings (single quotes, no escaping)
- Inline tables and arrays for compact representation of small structures
Common Use Cases
Rust Package Configuration
Cargo.toml defines Rust project metadata, dependencies, features, and build settings. TOML's explicit types prevent the configuration bugs common with YAML's implicit typing.
Python Project Configuration
pyproject.toml (PEP 518/621) is the modern standard for Python project metadata, build system configuration, and tool settings, replacing setup.py and setup.cfg.
Static Site Configuration
Hugo and other static site generators use TOML for site configuration. The format's readability and explicit types make site settings clear and unambiguous.