What is TOML? A practical guide to the config format
A plain-English guide to TOML—tables, arrays of tables, typed values and dates—with the syntax you actually meet in Cargo.toml and pyproject.toml.
Quick Answer
TOML is a configuration format designed to be obvious to read and write. It uses key-value pairs grouped into tables marked by bracket headers, supports explicit types including dates and adds arrays of tables for repeated sections. Cargo.toml and pyproject.toml are the files you meet it in most.
Search Snapshot
- Format
- Engineering
- Reading time
- 4 min
- Last updated
- June 12, 2026
- Primary topic
- what is TOML
- Intent
- informational
Key Takeaways
Point 1
TOML groups settings into [tables]; nested tables use dotted headers like [a.b].
Point 2
Values are explicitly typed—strings, integers, floats, booleans, dates, arrays.
Point 3
Repeated sections use [[array of tables]], which becomes a JSON array of objects.
If you have opened a Cargo.toml or pyproject.toml and wondered what the bracketed headers meant, this is for you. So what is TOML? It is a configuration format built around a single goal: be obvious. The name stands for Tom's Obvious Minimal Language and the syntax is deliberately plain so a config file means exactly what it appears to mean.
The basics: keys, values and comments
At its simplest TOML is key = value, one pair per line, with # starting a comment to the end of the line. Values are explicitly typed, which is a defining feature: a string is quoted, an integer is bare digits, a float has a decimal point, a boolean is true or false. There is no guessing whether 1.0 is a number or text—it is a float because it looks like one. TOML even has a native date-time type, something neither JSON nor most config formats offer.
Tables group related settings
A bracketed header like [database] starts a table and every key after it belongs to that table until the next header. Tables are how TOML expresses nesting. A dotted header such as [servers.alpha] nests one table inside another, so the keys below it live two levels deep. Paste any example into the TOML to JSON converter and the bracket headers turn into nested JSON objects, which makes the structure click immediately.
| TOML construct | Meaning | JSON equivalent |
|---|---|---|
| key = "value" | A typed key-value pair | A property |
| [table] | A group of keys | A nested object |
| [a.b] | A nested table | An object inside an object |
| [[items]] | A repeated section | An array of objects |
| [1, 2, 3] | An inline array | A JSON array |
| { x = 1, y = 2 } | An inline table | A small inline object |
TOML constructs and what they represent.
Arrays of tables for repeated sections
The construct that confuses newcomers is the double-bracket header, [[products]]. It marks an array of tables, which is TOML's way of writing a list of structured items. Each [[products]] block is one entry and several of them in a row form an array. When converted, those blocks become a JSON array of objects—the natural shape for a list. This is why a Rust manifest can declare several [[bin]] targets, each a complete object in its own right.
Where you meet TOML
The two files almost everyone encounters are Cargo.toml, the Rust package manifest and pyproject.toml, the modern Python project descriptor. Many other tools have adopted it for their config because its explicitness suits settings that humans edit and tools parse. If a file has bracketed section headers, key = value lines then # comments, it is TOML. To weigh it against the alternatives, see TOML vs JSON vs YAML for config files.
Frequently asked questions
What does TOML stand for?
Tom's Obvious Minimal Language. The name reflects the goal of a format that is obvious to read and minimal in syntax, aimed at hand-edited config.
What is an array of tables in TOML?
A repeated section written with double-bracket headers like [[products]]. Each block is one object and together they form a JSON array of objects when converted.
Bottom line
TOML is a config format that prizes being obvious: typed values, bracketed tables for nesting then double-bracket arrays of tables for repeated sections. Once those three ideas land, files like Cargo.toml read at a glance. Drop any example into the TOML to JSON converter to see its structure laid out as JSON.
Get new playbooks weekly
Actionable guides, market updates and shipping notes — once a week.