Introduction
TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be easy to read and write. It maps unambiguously to a hash table and is used by major projects like Rust's Cargo, Python's pip, and Hugo. If you work with modern developer tools, you've probably already used TOML without realizing it.
Basic Syntax
# This is a comment [server] host = "localhost" port = 8080 debug = true [database] host = "db.example.com" port = 5432 name = "myapp" max_connections = 20 timeout = 30.5
TOML uses [section] headers for nesting, key = value pairs for data, and # for comments. It's similar to INI files but with a strict specification and proper type support.
Data Types
| Type | Example | Notes |
|---|---|---|
| String | "hello" | Double or single quoted |
| Integer | 42 | No decimal point |
| Float | 3.14 | Must have decimal point |
| Boolean | true / false | Lowercase only |
| Array | [1, 2, 3] | Mixed types allowed |
| Datetime | 2024-01-15T10:30:00Z | RFC 3339 format |
Sections and Nesting
[owner] name = "Alice" email = "[email protected]" [server] host = "localhost" port = 8080 [server.ssl] cert = "/path/to/cert.pem" key = "/path/to/key.pem"
Sections create nested objects. [server.ssl] creates { server: { ssl: {...} } }. Indentation is optional but recommended for readability.
Array of Tables
Use [[products]] to create an array of tables:
[[products]]
name = "Hammer"
sku = 738594937
[[products]]
name = "Nail"
sku = 284758393
# Equivalent JSON:
# "products": [
# { "name": "Hammer", "sku": 738594937 },
# { "name": "Nail", "sku": 284758393 }
# ]Real-World Example: pyproject.toml
[project]
name = "my-package"
version = "1.0.0"
description = "A Python package"
requires-python = ">=3.9"
dependencies = [
"requests>=2.28",
"pydantic>=2.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0",
"ruff>=0.1",
]
[tool.ruff]
line-length = 88
target-version = "py39"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"When to Use TOML
- Configuration files - TOML was designed for config; it's the best choice for human-written settings
- Rust projects - Cargo.toml is the standard; you must use TOML
- Python packaging - pyproject.toml is the modern standard (PEP 517/518)
When Not to Use TOML
- API responses - Use JSON for universal compatibility
- Deeply nested data - TOML sections become verbose with deep nesting
- Complex data structures - YAML handles references and complex types better