What is TOML? A practical guide to the config format

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.

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.