TOML Formatter

Last updated: April 2026

What is TOML Formatting?

TOML (Tom's Obvious Minimal Language) is a configuration file format created by Tom Preston-Werner in 2013. It maps directly to a hash table and uses explicit typing for all values. A TOML formatter takes raw or inconsistently styled TOML and re-serializes it with uniform spacing, proper indentation, and canonical key ordering. The result is a file that follows the same conventions across your entire project, making config changes easier to review in diffs.

The TOML v1.0.0 specification, finalized in January 2021, defines the grammar strictly enough that any compliant parser produces an identical data structure from the same input. Formatting does not change the semantic content of a TOML file. It adjusts only whitespace, key grouping, and quoting style. This means you can format TOML files freely without worrying about breaking your application's behavior.

Unlike JSON, TOML supports comments, native date-time types, and multiple string forms (basic, literal, and multi-line). A good formatter preserves comments and respects the distinction between inline tables and standard table headers. It also handles arrays of tables correctly, keeping section grouping intact so the file stays readable for both humans and the parsers consuming it.

title="My App"
version="1.0.0"
debug=false
[database]
host="localhost"
port=5432
name="mydb"
[database.pool]
max_connections=25
timeout=30
[[servers]]
name="web"
host="web.example.com"
[[servers]]
name="api"
host="api.example.com"

title = "My App"
version = "1.0.0"
debug = false

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

[database.pool]
max_connections = 25
timeout = 30

[[servers]]
name = "web"
host = "web.example.com"

[[servers]]
name = "api"
host = "api.example.com"

Why Use a TOML Formatter?

Configuration files accumulate style drift as different team members edit them over time. Tabs mix with spaces, some keys get quoted unnecessarily, and table sections lose their visual grouping. A TOML formatter normalizes all of this in one pass.

TOML Formatter Use Cases

TOML Syntax Reference

TOML has a small set of constructs. The table below lists every structural element defined in the TOML v1.0.0 specification. A formatter applies consistent spacing and grouping to all of these.

TOML vs JSON vs YAML

TOML, JSON, and YAML solve overlapping problems but make different trade-offs.

Code Examples

The examples below format TOML programmatically across different languages and tools. Each reads a file, parses it, and writes a formatted version.

import { parse, stringify } from '@iarna/toml'
import fs from 'fs'

const raw = fs.readFileSync('config.toml', 'utf-8')
const doc = parse(raw)
const formatted = stringify(doc)
// stringify() outputs canonical TOML with consistent spacing
fs.writeFileSync('config.toml', formatted)

// Quick one-liner with npx:
// npx taplo fmt config.toml

import tomllib   # Python 3.11+ (read-only)
import tomli_w   # pip install tomli-w (write)

# Parse and re-serialize to format
with open("config.toml", "rb") as f:
    data = tomllib.load(f)

formatted = tomli_w.dumps(data)
# tomli_w produces sorted keys, consistent quoting, and
# proper whitespace around = signs
print(formatted)

# CLI alternative: taplo fmt config.toml

package main

import (
    "fmt"
    "os"
    "github.com/BurntSushi/toml"
    "bytes"
)

func main() {
    var data map[string]interface{}
    _, err := toml.DecodeFile("config.toml", &data)
    if err != nil {
        fmt.Fprintln(os.Stderr, err) // parse error with line number
        os.Exit(1)
    }
    var buf bytes.Buffer
    enc := toml.NewEncoder(&buf)
    enc.Indent = "  "
    enc.Encode(data) // re-serialized with consistent formatting
    fmt.Print(buf.String())
}

# Install taplo — the standard TOML toolkit
cargo install taplo-cli
# or: npm install -g @taplo/cli

# Format a single file in place
taplo fmt config.toml

# Format all .toml files in a project
taplo fmt

# Check formatting without modifying (CI-friendly)
taplo fmt --check

# Validate TOML syntax without formatting
taplo lint config.toml

Frequently Asked Questions