Guide · Open source

How to use TOML: syntax, examples and when to pick it

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

TOML (Tom's Obvious, Minimal Language) is a plain-text file format for configuration settings. Its rules are meant to be simple and obvious, and it maps unambiguously to a hash table, so programs can load it into data structures. This guide is for developers and smart non-experts who need to read or write a TOML file, and it explains what the format can and cannot do so you can decide whether it fits your project.

TOMLtoml-lang/toml · ★ 20.7k · MIT Install options & downloads

Quick start

1Read the spec overview. Start with the project README or toml.io to understand that TOML is a configuration file format built around a hash table at the top level.
2Learn the basic syntax. Practise with key-value pairs, strings in double quotes, comments starting with #, and [section] headers as shown in the README example.
3Write a small config file. Create a plain-text file with your settings, grouping related keys under section headers such as [database].
4Choose a parser for your language. Use the Official TOML Wiki to find an implementation in the language your project uses.
5Validate the file. Check your file with a validator listed in the wiki to catch syntax errors before your application loads it.
6Load it in your application. Use your chosen parser to read the file into your program's data structures.

What TOML is and what it is designed for

TOML is a specification for a plain-text file format used mainly for configuration settings. It aims to be a minimal format that is easy to read because its semantics are obvious. It is designed to map unambiguously to a hash table, and it should be easy to parse into data structures in many programming languages.

The specification is maintained in the toml-lang/toml repository, which holds the in-development version. Released versions are published at toml.io.

Read a TOML file: the basic syntax

A TOML document starts with key-value pairs and uses section headers in square brackets to group settings. Comments begin with a hash sign. The example below, taken from the project README, shows the main building blocks: comments, strings, dates, integers, booleans, arrays, nested tables and multi-line arrays.

Indentation is allowed but not required, so you can indent nested sections for readability.

Comments: lines starting with # (for example, # This is a TOML document.)
Strings are written in double quotes, such as title = "TOML Example"
Dates are first-class values, such as dob = 1979-05-27T07:32:00-08:00
Arrays use square brackets, such as ports = [ 8000, 8001, 8002 ]
Nested tables use dotted headers, such as [servers.alpha]
Arrays can span several lines, as long as line breaks are inside the brackets

# This is a TOML document.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates

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

[servers]

  # Indentation (tabs and/or spaces) is allowed but not required
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

Use TOML in a project: parsers and tooling

TOML is useful when you need a parser in the programming language you already use. The README says TOML should be easy to parse in a wide variety of languages, and it links to a wiki listing implementations, validators, editor support, encoders and converters.

This repository does not contain an application or install commands. To work with TOML in code, look up a parser for your language through the project wiki.

Browse the Official TOML Wiki for implementations in different languages
Check the wiki for validators to test a file against the spec
Check the wiki for editor support if you want syntax help while writing

Compare TOML with JSON, YAML and INI

TOML and JSON are both simple and use ubiquitous data types, which makes them easy for machines to parse. TOML and YAML both focus on human readability, including comments. TOML allows comments, unlike JSON, while keeping simpler rules than YAML.

INI files are often compared to TOML because their syntax is similar. However, INI has no standardized format and does not handle more than one or two levels of nesting well.

JSON: simple and machine-friendly, but no comments
YAML: readable and supports comments, but more complex
INI: similar look, but not standardized and weak with nesting
TOML: comments allowed, simple rules, nesting supported

Know the limits before you use TOML

TOML is intended as a configuration file format. It is not intended for serializing arbitrary data structures. A TOML document always has a hash table at the top level, and it does not allow top-level arrays or floats, so some data cannot be stored directly.

TOML also has no standard marker for the start or end of a file. That can complicate streaming, so applications must agree on those details themselves.

Not meant for serializing arbitrary data
No top-level arrays or floats
No standard start or end marker for streaming
This repository is the specification, not downloadable software

What people use it for

Application settings, such as server addresses, ports and feature flags
Tool configuration where comments explain why a value is set
Nested server or environment definitions, such as [servers.alpha] and [servers.beta]
Comparing config formats for a new project against JSON, YAML or INI

Frequently asked questions

What is TOML used for?

TOML is used mainly for configuration settings. The README describes it as a minimal format that is easy to read because its semantics are obvious. It is intended for configuration files rather than arbitrary data.

Is TOML free to use?

TOML is published under the MIT licence, according to the project information. The repository is the language specification.

Does TOML support comments?

Yes. Lines starting with # are comments. The README notes that this is a key difference from JSON, which does not allow comments.

Can TOML replace JSON or YAML?

It depends on the job. TOML is designed for configuration files. The README says it is not intended for serializing arbitrary data structures, and it does not allow top-level arrays or floats.

How do I install TOML?

The repository does not provide install commands. It holds the language specification, not an application. To use TOML, you pick a parser for your programming language from the Official TOML Wiki.

Why not use INI for configuration?

INI has no standardized format, and the README says it does not handle more than one or two levels of nesting well. TOML supports nested tables with a simple syntax.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

TOML suits developers who want a readable configuration file with comments and nested settings, without YAML's complexity. Pick another format if you need to serialize arbitrary data, use top-level arrays or floats, or need a standard file start and end marker for streaming. This repository is the specification itself, so you will need a parser from the wiki to use it in code.

Install options & downloads