TOML Cheatsheet
TOML (“Tom’s Obvious, Minimal Language”) is a config format designed to be easy to read and unambiguous to parse, with a formal spec and native types (unlike INI). It’s the standard for pyproject.toml, Cargo.toml, and many modern tool configs.
Basic Key-Value Pairs
title = "My App"
version = "1.0.0"
debug = true
port = 8080
ratio = 0.75
Data Types
string_basic = "hello world"
string_literal = 'C:\path\no\escapes\needed' # literal string — no escape processing
string_multiline = """
line one
line two
"""
string_multiline_literal = '''
raw content, no escapes
'''
integer = 42
integer_hex = 0xDEADBEEF
integer_octal = 0o755
integer_binary = 0b11010110
integer_underscore = 1_000_000 # underscores allowed for readability
float_val = 3.14
float_exp = 5e+22
float_infinity = inf
float_nan = nan
boolean_true = true
boolean_false = false
date_time = 2026-07-17T10:00:00Z
date_time_local = 2026-07-17T10:00:00
date_only = 2026-07-17
time_only = 10:00:00
Arrays
integers = [1, 2, 3]
strings = ["a", "b", "c"]
mixed_nested = [[1, 2], [3, 4, 5]]
floats = [1.1, 2.2, 3.3]
# Multi-line arrays (trailing comma allowed)
colors = [
"red",
"green",
"blue",
]
Tables (Sections)
[server]
host = "0.0.0.0"
port = 8080
[database]
url = "postgres://localhost/mydb"
timeout = 30
[database.pool] # nested table — equivalent to [database.pool]
min_size = 5
max_size = 20
# Inline table — compact syntax for a small table on one line
point = { x = 1, y = 2 }
owner = { name = "Subbarao", email = "you@example.com" }
Array of Tables
[[servers]]
name = "web1"
ip = "10.0.0.1"
[[servers]]
name = "web2"
ip = "10.0.0.2"
# Produces: servers = [{name="web1", ip="10.0.0.1"}, {name="web2", ip="10.0.0.2"}]
[[fruits]]
name = "apple"
[[fruits.varieties]] # nested array of tables
name = "red delicious"
[[fruits.varieties]]
name = "granny smith"
Dotted Keys
name.first = "Subbarao"
name.last = "K"
# Equivalent to:
# [name]
# first = "Subbarao"
# last = "K"
physical.color = "orange"
physical.shape = "round"
Comments
# This is a comment
key = "value" # inline comment
Common Real-World Examples
pyproject.toml (Python packaging)
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project]
name = "myapp"
version = "1.0.0"
description = "My application"
authors = [
{ name = "Subbarao", email = "you@example.com" }
]
requires-python = ">=3.11"
dependencies = [
"requests>=2.31",
"pandas>=2.0",
]
[project.optional-dependencies]
dev = ["pytest", "black", "ruff"]
[tool.black]
line-length = 100
target-version = ["py311"]
[tool.pytest.ini_options]
testpaths = ["tests"]
Cargo.toml (Rust)
[package]
name = "myapp"
version = "0.1.0"
edition = "2021"
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
[dev-dependencies]
criterion = "0.5"
[profile.release]
opt-level = 3
lto = true
poetry config (alternative Python packaging tool)
[tool.poetry]
name = "myapp"
version = "0.1.0"
description = ""
authors = ["Subbarao <you@example.com>"]
[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.31.0"
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Reading/Writing TOML in Python
import tomllib # built-in, Python 3.11+, READ-ONLY
with open("config.toml", "rb") as f: # note: must open in binary mode
data = tomllib.load(f)
data = tomllib.loads(toml_string)
# For writing, or Python < 3.11 reading, use a third-party library
import tomli_w
with open("out.toml", "wb") as f:
tomli_w.dump(data, f)
# tomlkit preserves comments/formatting on round-trip edits (useful for editing existing files)
import tomlkit
doc = tomlkit.parse(open("config.toml").read())
doc["server"]["port"] = 9090
open("config.toml", "w").write(tomlkit.dumps(doc))
TOML vs YAML vs INI vs JSON
| TOML | YAML | INI | JSON | |
|---|---|---|---|---|
| Native types | Yes (string, int, float, bool, datetime, array, table) | Yes | No — all strings | Yes |
| Comments | Yes (#) |
Yes (#) |
Yes (; or #) |
No |
| Nesting | Explicit [a.b.c] tables |
Indentation-based | Flat sections only | Native {} nesting |
| Multi-line strings | Yes (""") |
Yes (\|, >) |
Parser-dependent | No (needs \n escapes) |
| Ambiguity risk | Low — strict, well-specified | Higher (type coercion surprises, e.g. NO → false) |
High — no formal spec | Low |
| Common use | pyproject.toml, Cargo.toml, app config |
CI/CD, Kubernetes, Ansible, Docker Compose | Legacy app config, .gitconfig |
APIs, data interchange |
Advanced Parser & Schema Features
Different tools have unique TOML parsing rules:
- Strict Keys: Some tools enforce that keys with dots (
a.b = 1) cannot overlap with dynamically declared objects. - Heterogeneous Arrays: In TOML v0.5.0 and older, arrays could not contain mixed types. TOML v1.0.0 relaxes this constraint, letting you write
mixed = [1, "two", 3.0]. Always check your parser’s TOML version compatibility.
Common Gotchas
- Keys defined outside any table must come before the first
[table]header — you can’t add loose top-level keys after a table has started. - A table can only be defined once — redefining
[server]twice in the same file is an error (unlike INI, which sometimes silently merges or overwrites). - Dates/times without quotes are parsed as native TOML datetime values, not strings — quote them (
"2026-07-17") if you want a literal string. - Array of tables (
[[name]]) vs single table ([name]) is a common source of confusion — double brackets mean “append a new item to a list of tables under this key.” - Inline tables (
{ key = value }) must be on a single line — you cannot span an inline table across multiple lines (use a regular[table]instead if you need multi-line).