An Introduction to TOML Configuration

Learn the basics of TOML, the configuration format used by Rust, Python, and modern static site generators.

What is TOML?

TOML (Tom's Obvious, Minimal Language) is a configuration file format created by Tom Preston-Werner, co-founder of GitHub. It was designed to be easily readable by humans while mapping unambiguously to a hash table (dictionary/object) in memory.

Why Not Just Use YAML or JSON?

YAML can be overly complex and has surprising edge cases (like unquoted strings being evaluated as booleans or floating-point numbers).
JSON lacks comments and requires strict quoting and commas, making it annoying for human-maintained configuration.
INI files lack a standardized spec, meaning different parsers handle nesting and arrays differently.

TOML fixes these issues by providing a clear, standardized syntax for nested data structures.

TOML Syntax Basics

TOML uses a syntax similar to INI files, but with strict rules:

# This is a TOML document
title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First-class datetime support!

[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
connection_max = 5000
enabled = true

Where is TOML Used?

TOML has gained massive popularity in recent years and is the default configuration format for:

Rust (Cargo.toml)
Python (pyproject.toml)
Hugo (Static site generator)
Netlify (netlify.toml)