What is TOML?

What TOML is, and what it isn't

TOML is a data interchange format aimed at configuration. A TOML document is a tree of named tables, with each table holding key-value pairs. Every value has a clear, statically-knowable type: string, integer, float, boolean, datetime, array, or table. There is no null, no implicit type coercion, and no “smart” behaviour. If you wrote "true", the parser hands you a string; if you wrote true, you get a boolean.

TOML is not a programming language, a templating language, or a serialization format for arbitrary objects. It does one thing — describe a static configuration — and it does it in a way that is comfortable to write by hand and trivial to parse correctly.

Why it exists

Before TOML, configuration files in the open-source world drifted between three uncomfortable choices:

• INI — simple but underspecified. Every tool implements it slightly differently.
• JSON — strictly defined but unfriendly for humans: no comments, mandatory quoting, brace-heavy.
• YAML — friendly but error-prone. Indentation matters, and edge cases (NO becomes false, version strings get coerced into floats) bite people regularly.

TOML was published in 2013 as an attempt to give configuration files an obvious, minimal, rigorously specified format. The spec hit 1.0.0 in January 2021 after eight years of stabilisation. It is now used by major package managers including Cargo (Rust), Poetry / uv / Hatch / Flit (Python), and the wider pyproject.toml ecosystem defined by PEP 518 and PEP 621.

The shape of a TOML file

A TOML file looks like this:

title = "Example project"

[owner]
name = "Tom"
since = 2026-04-25T07:32:00Z

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

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

[[users]]
name = "Alice"
admin = true

[[users]]
name = "Bob"
admin = false

The top of the file may contain bare key-value pairs. Below the first bracketed header, every following key-value pair belongs to that table. Headers can be dotted ([servers.alpha] means: under servers, a sub-table called alpha). Double-bracket headers like [[users]] define an array of tables — append-style entries that decode into a list.

Types TOML supports

• String — single quotes (literal) or double quotes (escapes allowed); triple quotes for multi-line.
• Integer — decimal, hex (0x), octal (0o), or binary (0b); underscores allowed as separators.
• Float — including inf, -inf, nan.
• Boolean — always true or false, lowercase.
• Datetime — RFC 3339 offset datetime (1979-05-27T07:32:00Z), local datetime, local date, and local time.
• Array — homogeneous or mixed; trailing commas allowed.
• Table — either dotted headers, inline tables ({ a = 1, b = 2 }), or arrays of tables ([[name]]).

There is deliberately no null type. Missing data is expressed by omitting the key. This is the most common surprise for people coming from JSON or YAML.

TOML vs. JSON vs. YAML — which to use when

Rough rule of thumb: JSON for data interchange, YAML for long, deeply-nested CI/Kubernetes configuration, and TOML for handwritten, flat-ish configuration files that humans edit directly.

• Need to express null or pipe data through JavaScript? Use JSON.
• Need anchors, aliases, or 200-line nested manifests? Use YAML.
• Need a config file a human will hand-edit, where types must not be coerced and the format must be unambiguous? Use TOML.

The four converters on this site (TOML → JSON, JSON → TOML, TOML → YAML, YAML → TOML) handle the transitions, but a lossless round trip is only guaranteed for values both formats can represent natively. Comments and TOML-only datetime types are the two main casualties.

Where TOML shows up in real code

• Rust — Cargo.toml manifest, Cargo.lock lockfile, and most crate-level config (rustfmt.toml, rust-toolchain.toml).
• Python — pyproject.toml is the standard project manifest as of PEP 518/PEP 621, used by Poetry, uv, Hatch, Flit, Setuptools, Ruff, Mypy, Pytest, Black, and more.
• Go — popular for application configs via libraries like BurntSushi/toml; Hugo's main config is TOML.
• JavaScript / Node — Wrangler (Cloudflare Workers), Netlify (netlify.toml), and various build tools.
• Foundry — Ethereum smart-contract toolchain uses foundry.toml.
• Helm — chart-level configuration via Chart.toml in some ecosystems.

If you maintain dotfiles or a static-site generator config, you have probably already touched TOML without thinking about it.

Browser tools on this site

tomlkit.org runs everything in your browser. Pick the one that fits:

• TOML Formatter — canonical spacing, quoting, table layout. Strips comments.
• TOML Validator — pin syntax errors to the exact line and column.
• TOML → JSON — clean JSON output, dates as ISO 8601 strings.
• JSON → TOML — readable TOML out of a JSON object.
• TOML → YAML — YAML 1.2 output, useful for migrating into CI workflows.
• YAML → TOML — same shape, types preserved as far as TOML allows.
• Sample datasets — real-world Cargo.toml, pyproject.toml, and intentionally-broken files for testing.

Frequently asked

Is TOML faster to parse than JSON or YAML?

Roughly equivalent for typical config sizes. The bigger win is that TOML is unambiguous: a correct parser will always produce the same tree from the same input, with no language-level quirks the way YAML has.

Can TOML express deeply nested data?

Yes, but it doesn't try to be pretty about it. Five-level-deep configurations work fine via dotted headers ([a.b.c.d.e]), but if you find yourself nesting that far, the format is gently nudging you to flatten things out.

Does TOML support comments?

Yes. Anything from a # to the end of the line is a comment. They are part of the source file but not part of the data tree, which is why the converters on this site cannot carry them across formats.

What's the difference between TOML 0.5 and TOML 1.0?

1.0 stabilised the spec, clarified some date/time edge cases, made mixed-type arrays legal, and tightened a few syntax rules. Most older files still parse cleanly; most parsers updated within a release or two.

Where can I read the actual spec?

The canonical spec is at toml.io/en/v1.0.0. The source repository is github.com/toml-lang/toml, where the spec is maintained as Markdown.

— S., [email protected]