Skip to main content
🇪🇸 Español 🇧🇷 Português 🇩🇪 Deutsch
Image Converter Video Converter Audio Converter Document Converter
Tools Guides Formats Pricing API
Log In
Guide

TOML Format: The Complete Technical Guide

PC By Pablo Cirre •

What Is TOML?

TOML — Tom's Obvious, Minimal Language — is a configuration file format created by Tom Preston-Werner (co-founder of GitHub) in 2013. Its design goal is to be a minimal format that maps unambiguously to a hash table — a configuration file that is obvious to read and to write, with explicit typing and clear semantics that eliminate the surprising behaviors found in YAML and INI files.

TOML reached version 1.0.0 in January 2021 after years of refinement and community consensus. It is now the default configuration format for the Rust ecosystem (Cargo.toml), used by Python packaging tools (pyproject.toml), and adopted by many Go, PHP, and JavaScript projects.

Design Philosophy

TOML was built on specific design constraints:

  • Obvious: a human reading a TOML file should immediately understand the structure.
  • Minimal: only the features necessary for configuration, nothing more.
  • Unambiguous: every TOML file maps to exactly one data structure with no type coercion surprises.
  • Compatible with hash tables: designed for 1:1 mapping to key-value stores.

TOML deliberately avoids YAML's complexity (200+ page spec) and JSON's lack of comments. It is simpler than XML while being more structured than INI files.

Basic Syntax

# This is a TOML comment

# Key-value pairs (top-level table)
name = "KaijuConverter"
version = "2.1.0"
active = true
price = 9.99
max_connections = 100

# Dates and times (RFC 3339)
created_at = 2024-01-15T10:30:00Z
local_date = 2024-01-15          # date without time
local_time = 10:30:00            # time without date

# Multi-line basic string (backslash-escaped)
description = """
This is a
multi-line string.
"""

# Multi-line literal string (no escaping)
regex = '''
^[a-z]+$
'''

Tables (Objects)

Tables are the TOML equivalent of objects/dictionaries:

[database]
host = "localhost"
port = 5432
name = "kaijudb"
ssl = true

[database.pool]
min = 2
max = 20
timeout = 30

[server]
host = "0.0.0.0"
port = 8080

This maps to:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "kaijudb",
    "ssl": true,
    "pool": { "min": 2, "max": 20, "timeout": 30 }
  },
  "server": { "host": "0.0.0.0", "port": 8080 }
}

Dotted keys provide an inline shorthand for nested tables:

database.host = "localhost"
database.port = 5432

Arrays of Tables

[[double_brackets]] create arrays of tables — the TOML way to represent a list of objects:

[[servers]]
name = "web-01"
ip = "192.168.1.10"
role = "primary"

[[servers]]
name = "web-02"
ip = "192.168.1.11"
role = "replica"

[[servers]]
name = "web-03"
ip = "192.168.1.12"
role = "replica"

This maps to an array of server objects, equivalent to:

{
  "servers": [
    {"name": "web-01", "ip": "192.168.1.10", "role": "primary"},
    {"name": "web-02", "ip": "192.168.1.11", "role": "replica"},
    {"name": "web-03", "ip": "192.168.1.12", "role": "replica"}
  ]
}

Data Types

TOML has explicit, unambiguous types:

Type Example Notes
String "hello" or 'raw' Basic (escaped) or literal (no escape)
Integer 42, -7, 1_000_000 Underscores for readability
Float 3.14, 1.0e10, inf, nan IEEE 754 double
Boolean true, false Only lowercase
Datetime 2024-01-15T10:30:00Z RFC 3339 full; offset, local-datetime, local-date, local-time
Array [1, 2, 3] or ["a", "b"] Mixed types allowed in 1.0 but not recommended
Inline table {x = 1, y = 2} Single-line only; no trailing comma
Table [section] Block definition
Array of tables [[section]] Repeatable block

String types:

  • Basic string ("...") — supports escape sequences: \n, \t, \uXXXX, \\, \".
  • Literal string ('...') — no escaping; what you write is what you get.
  • Multi-line basic ("""...""") — leading newline after opening quotes is trimmed.
  • Multi-line literal ('''...''') — no escaping, raw content.

TOML in Practice: Cargo.toml

The Rust package manifest is the most widely used TOML file in the world:

[package]
name = "my-app"
version = "0.1.0"
edition = "2021"
authors = ["Alice <alice@example.com>"]
description = "A fast file converter"
license = "MIT"
repository = "https://github.com/alice/my-app"

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
reqwest = { version = "0.11", default-features = false, features = ["json"] }

[dev-dependencies]
mockall = "0.12"

[profile.release]
opt-level = 3
lto = true
strip = true

TOML in Python Packaging: pyproject.toml

PEP 518 and PEP 621 standardized pyproject.toml as the Python project descriptor:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = ["pytest", "mypy", "ruff"]

[tool.ruff]
line-length = 88
select = ["E", "F", "I"]

[tool.mypy]
strict = true

TOML vs. YAML vs. INI vs. JSON

Feature TOML YAML INI JSON
Comments Yes Yes Yes No
Explicit types Yes Partial No Yes
Multi-line strings Yes Yes No Escape only
Nested structures Yes (tables) Yes Limited (sections) Yes
Arrays of objects Yes ([[]]) Yes No Yes
Dates/times Native Coerced No No
Anchors/aliases No Yes No No
Schema standard No No No JSON Schema
Spec complexity Low Very high None Low
Ambiguity None High High None
Best for Config files CI/CD, K8s Simple settings APIs, data

TOML wins on explicitness and unambiguity. YAML wins on expressiveness and ecosystem breadth for DevOps. JSON wins for API interchange. INI is only acceptable for legacy compatibility.

Parsing TOML

Python:

import tomllib  # stdlib since Python 3.11

with open('config.toml', 'rb') as f:
    config = tomllib.load(f)

# For writing, use tomli-w (third-party)
import tomli_w
with open('output.toml', 'wb') as f:
    tomli_w.dump(data, f)

Rust (with serde):

use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
    name: String,
    version: String,
    database: DatabaseConfig,
}

let config: Config = toml::from_str(toml_str)?;

Go:

import "github.com/BurntSushi/toml"

var config Config
_, err := toml.Decode(tomlString, &config)

JavaScript/Node.js:

import { parse } from '@iarna/toml';
const config = parse(tomlString);

Converting TOML

  • TOML → JSON: yq e -o=json config.toml, Python json.dumps(tomllib.loads(s)).
  • TOML → YAML: yq e -o=yaml config.toml.
  • JSON → TOML: yq e -o=toml input.json.
  • YAML → TOML: yq e -o=toml input.yaml.

Best Practices

  1. Use TOML for configuration that humans edit — its explicit types eliminate surprises.
  2. Prefer [table] headers over deeply nested inline tables for readability.
  3. Use [[array of tables]] for lists of objects — cleaner than YAML sequences of mappings.
  4. Always use RFC 3339 datetimes — TOML's native date/time types prevent ambiguity.
  5. Use literal strings ('...') for regex patterns, file paths, and any string with backslashes.
  6. Use underscores in numbers for readability: 1_000_000 instead of 1000000.
  7. Validate schema with taplo (Rust-based TOML toolkit with JSON Schema integration).
  8. Sort keys alphabetically within tables for consistent diffs.
  9. Do not mix table definition and key-value assignment in different places.
  10. Prefer TOML over YAML for new projects where CI/CD YAML idioms are not required.

Related conversions

Frequent conversions across the catalogue:

Frequently Asked Questions

A single-bracket table header [name] defines a mapping (dictionary) under a key — it can only appear once per key. A double-bracket header [[name]] appends a new mapping to an array under that key — each occurrence adds one element to the array. Use [section] when you have a single configuration block (database settings, server config). Use [[servers]] when you need a list of similar objects (multiple server entries, plugin configurations, dependency overrides). The [[]] syntax is the TOML idiomatic replacement for YAML's "- key: value" list-of-mappings pattern.

A single-bracket table header [name] defines a mapping (dictionary) under a key — it can only appear once per key. A double-bracket header [[name]] appends a new mapping to an array under that key — each occurrence adds one element para o array. usar [section] when you have a single configuration block (database settings, server config). usar [[servers]] when you need a list of similar objects (multiple server entries, plugin configurations, dependency overrides). The [[]] syntax is the TOML idiomatic replacement para YAML's "- key: value" list-of-mappings pattern.

A single-bracket table header [name] defines a mapping (dictionary) under a key — it can only appear once per key. A double-bracket header [[name]] appends a new mapping to an array under that key — each occurrence adds one element zum array. verwenden [section] when you have a single configuration block (database settings, server config). verwenden [[servers]] when you need a list von similar objects (multiple server entries, plugin configurations, dependency overrides). The [[]] syntax is the TOML idiomatic replacement für YAML's "- key: value" list-of-mappings pattern.

A single-bracket table header [name] defines a mapping (dictionary) under a key — it can only appear once per key. A double-bracket header [[name]] appends a new mapping to an array under that key — each occurrence adds one element al array. usar [section] when you have a single configuration block (database settings, server config). usar [[servers]] when you need a list de similar objects (multiple server entries, plugin configurations, dependency overrides). The [[]] syntax is the TOML idiomatic replacement para YAML's "- key: value" list-of-mappings pattern.

On KaijuConverter every file is processed inside an isolated container, encrypted in transit (TLS 1.3) and at rest, and automatically deleted after 60 minutes with multi-pass overwrite. We never train on, share, or analyze user content. For maximum privacy on extremely sensitive material, prefer offline tools (ImageMagick, FFmpeg, LibreOffice) that you control end-to-end.

Python's built-in tomllib (added in Python 3.11) requires the file to be opened in binary mode ("rb") to ensure it reads raw bytes and applies its own UTF-8 decoding according to the TOML specification. This prevents platform-specific line-ending translations (Windows CRLF to LF) or encoding auto-detection from corrupting the parse. The API is tomllib.load(binary_file_object) or tomllib.loads(string). For Python < 3.11, use the third-party tomli package which has an identical API.

For 95% of use cases, yes — server-side ImageMagick, FFmpeg and LibreOffice produce identical output to the same tools on your laptop. Desktop software wins for: extremely large files (multi-GB), batch jobs of thousands of files, scripted pipelines, or content too sensitive to upload. KaijuConverter caps at 25 MB per file on the free tier (up to 2 GB on paid plans).

Choose TOML when: (1) humans will manually edit the configuration frequently — TOML's explicit types prevent accidental boolean/number coercion; (2) you are building a Rust project (Cargo.toml is mandatory) or a Python package (pyproject.toml is the standard); (3) you want minimal parser complexity and a short, unambiguous specification; (4) your config has lists of objects (arrays of tables are cleaner than YAML's indented list syntax). Choose YAML when: you need to integrate with existing Kubernetes, GitHub Actions, or Ansible ecosystems where YAML is the enforced standard, or when you need anchors/aliases for DRY configuration.

Escolha TOML quando: (1) humanos editem frequentemente a configuração à mão — os tipos explícitos do TOML previnem coerções acidentais boolean/number; (2) construa um projeto Rust (Cargo.toml é obrigatório) ou um pacote Python (pyproject.toml é o padrão); (3) queira complexidade mínima de parser e uma especificação curta e sem ambiguidades; (4) sua config tenha listas de objetos (arrays de tables são mais limpos que a sintaxe de listas indentadas do YAML). Escolha YAML quando precisar integrar com ecossistemas existentes (Kubernetes, GitHub Actions, Ansible) onde YAML é o padrão imposto, ou quando precisar de anchors/aliases para configuração DRY.

Wähle TOML, wenn: (1) Menschen die Konfiguration häufig manuell bearbeiten — TOMLs explizite Typen verhindern versehentliche Boolean/Number-Coercions; (2) du ein Rust-Projekt baust (Cargo.toml ist verpflichtend) oder ein Python-Paket (pyproject.toml ist Standard); (3) du minimale Parser-Komplexität und eine kurze, eindeutige Spezifikation willst; (4) deine Config Listen von Objekten enthält (Arrays von Tables sind sauberer als YAMLs eingerückte Listen-Syntax). Wähle YAML, wenn du in bestehende Ökosysteme integrieren musst (Kubernetes, GitHub Actions, Ansible), wo YAML der erzwungene Standard ist, oder wenn du Anchors/Aliases für DRY-Konfiguration brauchst.

Elige TOML cuando: (1) los humanos editen frecuentemente la configuración a mano — los tipos explícitos de TOML evitan coerciones accidentales boolean/number; (2) construyas un proyecto Rust (Cargo.toml es obligatorio) o un paquete Python (pyproject.toml es el estándar); (3) quieras complejidad mínima de parser y una especificación corta y sin ambigüedades; (4) tu config tenga listas de objetos (los arrays de tablas son más limpios que la sintaxis de listas indentadas de YAML). Elige YAML cuando necesites integrar con ecosistemas existentes (Kubernetes, GitHub Actions, Ansible) donde YAML es el estándar impuesto, o cuando necesites anchors/aliases para configuración DRY.

Most format conversions are lossy by design — JPG, MP3, MP4, WebP all discard perceptual data to save bytes. Going through a lossy intermediate compounds the loss. To minimize visible/audible drift: convert from the original master, choose a higher quality setting, and avoid converting back and forth between lossy formats.

TOML has four native temporal types: offset datetime (2024-01-15T10:30:00Z), local datetime (2024-01-15T10:30:00 without timezone), local date (2024-01-15), and local time (10:30:00). These are first-class types — parsers return proper date/time objects, not strings. YAML 1.1 also recognizes dates but via implicit coercion that can cause surprises (date strings in config being parsed as Date objects unexpectedly). JSON has no date type at all — dates are strings by convention. For any configuration with meaningful timestamps, TOML's native date handling eliminates ambiguity and timezone bugs.

TOML has four native temporal types: offset datetime (2024-01-15T10:30:00Z), local datetime (2024-01-15T10:30:00 sem timezone), local date (2024-01-15), e local time (10:30:00). These are first-class types — parsers return proper date/time objects, not strings. YAML 1.1 also recognizes dates mas via implicit coercion that can cause surprises (date strings in config being parsed as Date objects unexpectedly). JSON has no date type at all — dates are strings by convention. para any configuration com meaningful timestamps, TOML's native date handling eliminates ambiguity e timezone bugs.

TOML has four native temporal types: offset datetime (2024-01-15T10:30:00Z), local datetime (2024-01-15T10:30:00 ohne timezone), local date (2024-01-15), und local time (10:30:00). These are first-class types — parsers return proper date/time objects, not strings. YAML 1.1 also recognizes dates aber via implicit coercion that can cause surprises (date strings in config being parsed as Date objects unexpectedly). JSON has no date type at all — dates are strings by convention. für any configuration mit meaningful timestamps, TOML's native date handling eliminates ambiguity und timezone bugs.

TOML has four native temporal types: offset datetime (2024-01-15T10:30:00Z), local datetime (2024-01-15T10:30:00 sin timezone), local date (2024-01-15), y local time (10:30:00). These are first-class types — parsers return proper date/time objects, not strings. YAML 1.1 also recognizes dates pero via implicit coercion that can cause surprises (date strings in config being parsed as Date objects unexpectedly). JSON has no date type at all — dates are strings by convention. para any configuration con meaningful timestamps, TOML's native date handling eliminates ambiguity y timezone bugs.

Yes — KaijuConverter accepts multiple files in a single drop and returns a ZIP. For very large batches (thousands of files) consider command-line tools or our API: <code>find . -name "*.heic" -exec magick {} {.}.jpg \;</code> or similar one-liners scale to millions of files when run locally.

We use cookies and similar technologies to personalise content and ads, and to analyse traffic. Learn more about cookies.