The TOML file (.toml)

The basics

What is a TOML file?

Anatomy

What's inside a TOML file

A TOML file is a list of key = value pairs. [table] headers group the pairs that follow them, and every value has an explicit type you can tell from how it's written. Here is a small but complete file, part by part.

# Settings for a small web app
title = "Sample app"
version = "2.10"
debug = false
port = 8080
ratio = 0.75
released = 2026-10-27T09:30:00Z
languages = ["en", "nl"]
owner = { name = "Ada Example", email = "ada@example.com" }

[database]
host = "db.example.internal"
pool.max = 10

[database.replica]
host = "replica.example.internal"

[[servers]]
name = "web-1"

[[servers]]
name = "web-2"

1. 1# Settings for a small web app

   A comment

   Everything from # to the end of the line is ignored, unless the # is inside a string.

2. 2title = "Sample app"

   A key and a string

   Keys go on the left of =, values on the right. Strings always need quotes: unlike YAML or INI, a bare word is an error, not text.

3. 3version = "2.10"

   A version kept as text

   Because strings are always quoted, "2.10" can never turn into the number 2.1, the classic YAML trap.

4. 4debug = false

   A boolean

   Only lowercase true and false. yes, on and True are errors.

5. 5port = 8080 ratio = 0.75

   An integer and a float

   Integers are 64-bit, may use _ as a separator (1_000_000) and may be written in hex, octal or binary (0xFF, 0o755, 0b1010). Floats need a digit on both sides of the point, and inf and nan are allowed.

6. 6released = 2026-10-27T09:30:00Z

   A date and time

   A native type, written as in RFC 3339. This one is a moment in UTC; TOML also has local date-times without a time zone, plain dates and plain times.

7. 7languages = ["en", "nl"]

   An array

   Values in square brackets, separated by commas. Arrays may span several lines and end with a trailing comma.

8. 8owner = { name = …, email = … }

   An inline table

   A small table written on one line. In TOML 1.0 it must stay on one line, with no trailing comma; TOML 1.1 relaxes both rules.

9. 9[database]

   A table header

   Starts a table: every key below it, up to the next header, belongs to database. Indenting the keys is allowed but means nothing.

10. 10pool.max = 10

    A dotted key

    Creates nested tables on the fly: this is database.pool.max. Dotted keys and headers are two ways of writing the same structure.

11. 11[database.replica]

    A sub-table

    A dotted header creates a table inside database. The parent doesn't need a header of its own.

12. 12[[servers]]

    An array of tables

    Double brackets add a new table to the servers list each time they appear, the TOML way to write a list of records.

How it works

How TOML turns into data

{
  "title": "Sample app",
  "version": "2.10",
  "debug": false,
  "port": 8080,
  "ratio": 0.75,
  "released": "2026-10-27 09:30:00+00:00",
  "languages": ["en", "nl"],
  "owner": { "name": "Ada Example", "email": "ada@example.com" },
  "database": {
    "host": "db.example.internal",
    "pool": { "max": 10 },
    "replica": { "host": "replica.example.internal" }
  },
  "servers": [{ "name": "web-1" }, { "name": "web-2" }]
}

Versions

TOML 1.0 and TOML 1.1

# TOML 1.0: an inline table must fit on one line
owner = { name = "Ada Example", email = "ada@example.com" }

# TOML 1.1: it may span lines and end with a comma
owner = {
  name = "Ada Example",
  email = "ada@example.com",
}

Comparison

TOML vs YAML, JSON and INI

Troubleshooting

Why won't my TOML file load?

How to

How to open, edit and convert a TOML file

import json, tomllib

with open("config.toml", "rb") as f:   # tomllib wants binary mode
    data = tomllib.load(f)

print(json.dumps(data, indent=2, default=str))   # dates become strings

Security

Is a TOML file safe? Secrets and build files

Free downloads

Sample TOML files to download

Free sample TOML files for testing parsers, config loaders, editors and upload limits. All except sample-toml-1.1.toml are valid TOML 1.0 and load in Python's tomllib, tomli, tomlkit and smol-toml.

Loading…

What's inside sample-config.toml

The file is commented: each numbered comment marks one of these parts.

1. Comments 1 to 4: root keys and simple values

   Strings, a quoted version number, a boolean, integers with underscores and in octal, a float and inf.

2. Comment 5: dates and times

   All four kinds: an offset date-time, a local date-time, a local date and a local time.

3. Comments 6 and 7: strings

   A basic string with \", \t and \u00e9 escapes, literal strings for a Windows path and a regular expression, and a multi-line string.

4. Comments 8 and 9: arrays and an inline table

   A one-line array, a multi-line array with a trailing comma, and an owner inline table.

5. Comments 10 to 12: tables

   A [database] table, dotted keys that create database.pool, and a [database.replica] sub-table.

6. Comment 13: quoted keys

   Keys with a space, an accent and a dot, which need quotes.

7. Comment 14: an array of tables

   Two [[servers]] entries that load as a list of two tables.

All sample TOML files

• Commented config file

  sample-config.toml · 2.3 KB (2,359 bytes)

  An app configuration with 14 numbered comments covering every value type, all four date and time types, the four kinds of strings, tables, dotted keys, quoted keys and an array of tables.

  • Teaching the parts of a TOML file
  • Testing config loaders and type handling
  DownloadOpen

• pyproject.toml for a fictional package

  sample-pyproject.toml · 1.3 KB (1,355 bytes)

  Packaging metadata in the standard [build-system] and [project] tables, with dependencies, optional dependencies, a script entry point and [tool.*] settings for Ruff and pytest.

  • Testing tools that read `pyproject.toml`
  • A starting point for a new Python package
  DownloadOpen

• Cargo.toml for a fictional crate

  sample-cargo.toml · 1.0 KB (1,056 bytes)

  A Rust manifest with dependencies as strings and inline tables, dev-dependencies, features, a [[bin]] array of tables and a release profile. Rename it to Cargo.toml to use it.

  • Testing tools that read Cargo manifests
  • Seeing inline tables and arrays of tables in real use
  DownloadOpen

• TOML 1.1 features (rejected by 1.0 parsers)

  sample-toml-1.1.toml · 859 bytes

  A multi-line inline table with a trailing comma, the new \e and \xHH escapes and times without seconds. Valid TOML 1.1.0; a parser that supports only 1.0 should report an error.

  • Finding out which TOML version a parser supports
  • Testing error reporting
  DownloadOpen

• Non-ASCII text with CRLF line endings

  sample-unicode-crlf.toml · 794 bytes

  Greetings in eight scripts and emoji, the same characters as \u and \U escapes, quoted keys such as "€", and a multi-line string, saved with Windows line endings.

  • Spotting encoding bugs
  • Checking CRLF handling in multi-line strings
  DownloadOpen

• 100 KB TOML file

  sample-100kb.toml · 100 KB (102,400 bytes)

  714 fictional sensors as an array of tables, padded with a final comment to exactly 102,400 bytes.

  • Upload and size-limit tests
  • Parser performance
  DownloadOpen

Ways to test with them

• Which version your parser supports: load sample-toml-1.1.toml. An error at the owner table means TOML 1.0 only.
• Types: load sample-config.toml and check that version is a string, permissions is 493, timeout is infinity and launch_day is a date.
• Line endings: in sample-unicode-crlf.toml, notes.text should come back as two lines; check whether your parser keeps the CR.
• Upload limits: sample-100kb.toml is exactly 102,400 bytes, for testing a limit at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

TOML files, frequently asked