What is TOML?

TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be easy to read and write. It's similar to INI files but with a well-defined specification. TOML is the standard format for Rust's Cargo, Python's pyproject.toml, and many other modern tools.

TOML Syntax

TOML uses a simple key-value syntax with support for tables (sections), arrays, and various data types. Comments start with a hash (#) character.

Basic TOML Example

# This is a comment
title = "My Application"
version = "1.0.0"

[owner]
name = "John Doe"
email = "john@example.com"

[database]
host = "localhost"
port = 5432
enabled = true

[servers]
  [servers.alpha]
  ip = "10.0.0.1"
  role = "frontend"

  [servers.beta]
  ip = "10.0.0.2"
  role = "backend"

Data Types

TOML supports several data types:

Strings

# Basic string
name = "John Doe"

# Multi-line string
description = """
This is a multi-line
string that preserves
line breaks."""

# Literal string (no escapes)
path = 'C:\Users\name'

Numbers

# Integer
port = 8080
negative = -42

# Float
pi = 3.14159
scientific = 6.022e23

# Underscores for readability
large_number = 1_000_000

Booleans and Dates

# Boolean
enabled = true
debug = false

# Date and time
created = 2024-01-15
updated = 2024-01-15T10:30:00Z
local_time = 10:30:00

Arrays

# Simple array
ports = [8080, 8081, 8082]

# Mixed types not allowed in strict TOML
tags = ["web", "api", "backend"]

# Multi-line array
features = [
  "feature1",
  "feature2",
  "feature3",
]

Tables (Sections)

Tables in TOML are collections of key-value pairs, similar to objects in JSON or dictionaries in Python.

Standard Tables

[database]
host = "localhost"
port = 5432
name = "myapp"

[database.connection]
timeout = 30
retries = 3

Array of Tables

[[products]]
name = "Hammer"
price = 9.99

[[products]]
name = "Nail"
price = 0.05

This creates an array of product objects.

Real-World Examples

Cargo.toml (Rust)

[package]
name = "my-project"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <you@example.com>"]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[dev-dependencies]
assert_cmd = "2.0"

pyproject.toml (Python)

[project]
name = "my-package"
version = "1.0.0"
description = "A Python package"
requires-python = ">=3.8"

[project.dependencies]
requests = ">=2.28"
click = ">=8.0"

[tool.black]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]

TOML vs Other Formats

When to Use TOML

Related Tools