TOML cheat sheet
Summary
This comprehensive TOML cheat sheet provides quick-reference examples for all key language features including tables, arrays, data types, and formatting rules. It covers syntax essentials and best practices for working with TOML configuration files.
Introduction #
TOML stands for Tom’s Obvious, Minimal Language. It is a configuration file format that aims for readability and a clear specification.
You can use TOML for software projects that require human-readable and easy-to-edit configuration files. TOML files must be valid UTF-8.
This cheat sheet summarizes the TOML format using examples and concise explanations. It covers keys, values, data types, tables, arrays, comments, and best practices.
File Structure #
TOML files consist of key-value pairs, tables, and arrays. Keys appear on the left, and values appear on the right, separated by an equals sign.
title = "TOML Example"
Whitespace around the equals sign is allowed but not required.
Keys and Values #
Keys must be strings without special characters. Use double quotes for keys with spaces or reserved characters.
key = "value"
"complex key" = "value"
"key.with.dots" = "value"
Value Types #
Quick Reference #
| Type | Example |
|---|---|
| String | str = "Hello" |
| Integer | num = 42 |
| Float | pi = 3.14 |
| Boolean | flag = true |
| Datetime | when = 2025-06-05T12:00:00Z |
| Array | list = [1, 2, 3] |
| Table | [table] + key = value |
| Array Table | [[array_table]] |
| Inline Table | config = { key = value } |
Strings #
Use double quotes for basic strings, single quotes for literal strings, and triple quotes for multiline strings.
basic = "A string with \"quotes\" and \\backslashes\\"
literal = 'No escape needed: \n stays as-is'
multiline = """This string
spans multiple lines."""
Numbers #
TOML supports integers and floats. Use underscores for readability.
int = 1000
float = 3.1415
large = 1_000_000
hex = 0xDEADBEEF
oct = 0o755
bin = 0b11010110
Booleans #
Boolean values are written as true or false.
enabled = true
disabled = false
Date and Time #
TOML supports RFC 3339 format for date and time.
dob = 1987-07-01T13:45:00Z
date_only = 2025-06-05
Special Float Values #
positive_inf = inf
negative_inf = -inf
not_a_number = nan
Arrays #
Arrays hold values of the same type. Separate elements with commas and use square brackets.
fruits = ["apple", "banana", "cherry"]
numbers = [1, 2, 3]
mixed = [[1, 2], [3, 4]] # Arrays must be homogeneous
Tables and Structures #
Regular Tables #
Tables group related key-value pairs. Declare tables with square brackets [].
[server]
ip = "127.0.0.1"
port = 8080
Nested Tables #
Use dot notation or multiple bracketed declarations.
[server.settings]
timeout = 30
# Equivalent to:
[server]
[server.settings]
timeout = 30
Arrays of Tables #
Use double square brackets for arrays of tables.
[[users]]
name = "Alice"
age = 30
[[users]]
name = "Bob"
age = 25
Inline Tables #
Inline tables define key-value pairs on a single line using curly braces.
config = { timeout = 5, retries = 3 }
Table vs Inline Table Usage #
Regular tables are better for:
- Multiple related settings
- Better readability for complex configurations
[server]
host = "example.com"
port = 443
Inline tables are better for:
- Simple one-off groupings
- When compactness is preferred
connection = { host = "example.com", port = 443 }
Comments #
Begin comments with #. Comments can appear on their own line or at the end of a line.
# This is a comment
name = "value" # This is also a comment
Best Practices #
- Ordering: Place root tables before nested ones
- Grouping: Keep related settings together
- Comments: Use comments to explain non-obvious settings
- Formatting: Be consistent with indentation and spacing
Reserved characters #
TOML reserves certain characters and does not allow them unescaped in keys or strings:
.(dot) separates nested keys#introduces comments"and'denote strings
FAQ's #
Most common questions and brief, easy-to-understand answers on the topic:
What does TOML stand for?
TOML stands for Tom's Obvious, Minimal Language, a configuration file format designed to be easy to read and unambiguous.
Is TOML used in programming projects?
Yes, TOML is widely used in tools and environments like Rust's Cargo, Python's PEP 518, and various static site generators.
Can TOML handle nested data?
Yes, TOML supports nested tables and arrays of tables to represent structured data hierarchies.
Does TOML support comments?
Yes, TOML supports comments using the # character, and comments can be placed above or after a line of configuration.
Is TOML case-sensitive?
Yes, keys in TOML are case-sensitive, so title and Title are treated as different keys.
Further readings #
Sources and recommended, further resources on the topic:
- TOML Official Site
- GitHub: TOML Language Specification
- PSF: Python TOML parsing (tomllib)
- Rust: Cargo Manifest Format
Author
Jonas Jared Jacek (J15k)
Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/License
TOML cheat sheet by Jonas Jared Jacek is licensed under CC BY-SA 4.0.
This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:
<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/toml-cheat-sheet">TOML cheat sheet</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>For more information see the Ditig legal page.
