What Is a TOML File? A Beginner's Guide to the Config Format

If you have opened a Rust, Python or static-site project recently, you have probably met a .toml file: Cargo.toml, pyproject.toml, a site configuration. TOML is a plain-text format built for one purpose, configuration files that are easy for humans to read and write.

What TOML stands for

TOML is short for Tom's Obvious, Minimal Language, named after its creator, Tom Preston-Werner, a co-founder of GitHub. The goal in its own words is a minimal configuration format that is easy to read thanks to obvious semantics and maps unambiguously to a hash table, also known as a dictionary or map. The current specification is TOML 1.0, and files use the .toml extension.

A first look

# This is a comment
title = "My Project"
version = "1.6.0"
debug = false
ports = [80, 443]

[database]
host = "localhost"
port = 5432

[database.options]
timeout = 30

You can read that without any instructions. Settings are key = value lines, section headings are in square brackets and comments start with #.

The building blocks

• Key/value pairs: name = "value". Keys can be bare (letters, digits, dashes, underscores) or quoted.
• Strings: basic strings in double quotes with escapes, literal strings in single quotes with no escapes, and multi-line versions of both with triple quotes.
• Numbers: integers (with optional _ separators, such as 1_000), floats, and hex, octal and binary forms.
• Booleans: true and false, lowercase only.
• Dates and times: first-class types. 2025-04-03, 07:30:00 and 2025-04-03T07:30:00Z are dates and times, not strings.
• Arrays: [1, 2, 3], which may span lines and include a trailing comma.
• Tables: sections introduced by [name], with dotted names like [a.b] for nesting.
• Inline tables: point = { x = 1, y = 2 }, for small mappings on one line.
• Arrays of tables: [[products]], repeated to create a list of records.

See TOML syntax: tables, arrays and dates for the details.

What makes TOML different

• No indentation sensitivity. Indenting is for readability only, so a misplaced space does not change the meaning, unlike YAML.
• Types are explicit. A string is always quoted, so no is never silently turned into a boolean and 1.10 in quotes stays text.
• Comments are allowed, unlike in JSON.
• Duplicate keys are errors, not silently overwritten.
• Case-sensitive.

Where TOML is used

• Rust's package manager (Cargo.toml)
• Python packaging (pyproject.toml)
• Static site generators and developer tools that adopted it for configuration
• Application settings where a human edits the file

Limits

TOML is built for configuration, not for large or deeply nested data. Deep nesting becomes awkward, and there is no standard way to express a top-level array or null. For data exchange, JSON is the usual choice, and for complex configuration with reuse, some people prefer YAML. A comparison is in TOML vs YAML vs JSON for configuration.

How to open and edit a TOML file

It is plain text, so any editor works. For error checking, Docento's Text & Markdown Editor opens .toml files locally in your browser, shows them in a fixed-width font and reports a TOML error when the file does not parse. The Docento Android app does the same on a phone.

Takeaway

TOML is a minimal, explicit configuration format with sections, typed values and comments, and without indentation rules. It is a good fit for hand-edited settings files, and a syntax check catches mistakes quickly.