Typical reasons to switch
Teams move configuration from YAML to TOML mostly to escape YAML’s indentation and implicit typing: TOML has explicit types, no significant whitespace and no Norway problem. Typical migrations include a Python project replacing a YAML settings file with pyproject.toml, a static site moving from config.yaml to hugo.toml, or a Rust service adopting the ecosystem’s default format.
The TOML vs YAML guide covers the trade-offs in depth. This page focuses on what the conversion does with your data.
From YAML structures to TOML tables
The YAML is parsed as YAML 1.2 and then rebuilt as TOML:
- The root must be a mapping. A YAML file whose top level is a list — or a stream of several
---documents, which is read as a list — is rejected, because a TOML document is always a table. - Nested mappings become
[section]headers, with dotted names for deeper levels ([server.tls]). - A list of mappings becomes an array of tables: one
[[users]]block per item. - Lists of scalars, and lists mixing scalars with mappings, are written inline as
[ 1, "a" ]. - Flow mappings like
pool: { min: 2, max: 10 }are treated like any other mapping and get their own table.
Plain key/value pairs must precede table headers in TOML, so simple values are written first and sub-tables after them. A key that sat between two nested blocks in the YAML may therefore move up.
Types, anchors and values TOML cannot hold
Because parsing follows YAML 1.2, yes/no/on/off arrive in TOML as strings, while true/false become TOML booleans. Integers and floats keep their values, and integers too large for a double keep all their digits.
An unquoted date like 2024-01-01 is a string under YAML 1.2, so it is written as "2024-01-01" rather than a TOML local date. Anchors and aliases are expanded into full copies, since TOML has no reference syntax.
TOML has no null either. Keys whose value is null or ~, and null list items, are left out, and a warning lists their paths so you can decide what to put there instead.
Comments
TOML supports comments, but this converter rebuilds the document from data, and YAML comments are not attached to the data. They are dropped, and an info message tells you when the input had any. If your YAML is heavily commented, convert first and then copy the important comments across by hand; TOML uses the same # syntax, so they paste in unchanged.
No options needed
There are no settings to configure. Check the output in the TOML formatter, which also validates it, or open the YAML to JSON converter to see the intermediate data if something looks off. All of this happens locally, which matters for configs that hold database passwords or API keys.
Examples
Service config with nested tables
database and its pool become [database] and [database.pool]; debug moves above the tables because TOML requires it.
service: checkout
replicas: 3
database:
host: db.internal
port: 5432
pool: { min: 2, max: 10 }
features:
- payments
- refunds
debug: false
service = "checkout"
replicas = 3
features = [ "payments", "refunds" ]
debug = false
[database]
host = "db.internal"
port = 5432
[database.pool]
min = 2
max = 10
List of mappings and a null
The steps list becomes two [[steps]] blocks, and retry is omitted with a warning because TOML cannot express null.
name: nightly
schedule: "0 3 * * *"
retry: ~
steps:
- run: npm ci
timeout: 300
- run: npm test
timeout: 600
name = "nightly"
schedule = "0 3 * * *"
[[steps]]
run = "npm ci"
timeout = 300
[[steps]]
run = "npm test"
timeout = 600
Common errors and how to fix them
| Error | Cause | Fix |
|---|---|---|
TOML needs a table (an object) at the top level | The YAML starts with a list, or contains several documents separated by —, which are combined into a list. | Put the list under a key (items: […]) or convert one document at a time. |
TOML has no null, so 2 null values were left out: … | A warning listing keys or list items whose YAML value was null or ~. | Give those keys a concrete value in the YAML if the application needs them present. |
Tabs are not allowed for indentation in YAMLExplained | The YAML input is indented with a tab character, so it cannot be parsed. | Re-indent with spaces and convert again. |
Duplicate key — keys in a mapping must be uniqueExplained | Two identical keys exist in the same YAML mapping. | Remove one of them; TOML would reject the duplicate as well. |
Frequently asked questions
Are YAML comments copied into the TOML?
No, comments are dropped and an info note says so. TOML uses # comments too, so you can paste the ones you need back in.
Why is a date in my YAML a quoted string in the TOML?
Under YAML 1.2 an unquoted 2024-01-01 is plain text, and the converter keeps types as parsed. Remove the quotes in the TOML if you want a native local date.
What happens to anchors and aliases?
Each alias is expanded into a full copy of the anchored value, because TOML has no way to reference another part of the document.
Can I convert a multi-document YAML file?
Not in one go: several documents become a list, and TOML needs a table at the root. Convert each document separately.