What Is a TOML File? A Beginner's Guide
TOML explained for beginners — what it is, why projects like Cargo and pyproject use it, its syntax for tables and arrays, and how it compares to JSON and YAML.
If you've opened a Cargo.toml or pyproject.toml and wondered what TOML is, this guide is for you. TOML (Tom's Obvious, Minimal Language) is a configuration format designed to be easy for humans to read and write, with unambiguous types.
Why TOML exists
Config formats force a trade-off. JSON is strict but noisy and has no comments. YAML is readable but its whitespace rules and type coercion cause subtle bugs. TOML aims for the middle: obvious syntax, real types, comments, and no significant whitespace.
Basic syntax
TOML looks like an INI file with proper types:
# This is a comment
title = "My Application"
version = "1.0.0"
port = 8080
debug = false
Strings are quoted, numbers and booleans are bare. Indentation is purely cosmetic.
Tables (nested sections)
Nesting uses table headers in brackets:
[database]
host = "localhost"
port = 5432
[server]
host = "0.0.0.0"
port = 8080
Each header starts a new section. You can nest further with dotted names like [server.tls].
Arrays and arrays of tables
tags = ["web", "api", "backend"]
[[users]]
name = "alice"
[[users]]
name = "bob"
A single bracket is a table; double brackets define repeated tables (an array of objects).
Where you'll see TOML
- Rust —
Cargo.tomlfor package metadata and dependencies. - Python —
pyproject.tomlis now the standard project config. - Many Go and Rust CLIs use TOML for app config.
TOML vs JSON vs YAML
Choose TOML for human-edited project config, JSON for data interchange, and YAML for deeply nested cloud-native config. For a full breakdown, see JSON vs YAML vs TOML.
Check your TOML
Paste any TOML into the validator to catch duplicate tables, unclosed strings, and syntax errors with plain-English explanations — or use the formatter to convert it to JSON or YAML.