How to convert YAML to TOML
YAML and TOML both hold nested settings, lists, text, numbers and true or false. To convert yaml to toml, the tool reads your YAML, resolves anything YAML-only such as anchors, and writes the same data using TOML tables: a heading in square brackets for each nested map, with plain key = value lines under it.
The built-in sample is an Alacritty terminal config. Its window block starts like this:
window:
padding: { x: 6, y: 6 }
opacity: 0.95
font:
normal:
family: JetBrains Mono
style: Regular
size: 12.5With the default options it becomes:
[window]
opacity = 0.95
[window.padding]
x = 6
y = 6
[font]
size = 12.5
[font.normal]
family = "JetBrains Mono"
style = "Regular"TOML wants plain keys before sub-tables, so opacity moves above [window.padding]. The whole sample reports 25 keys, 8 tables and 33 lines. The key_bindings list of objects becomes one double-bracket block per item, each headed by the list name.
What TOML cannot store, and how the tool tells you
TOML has no null, no anchors and no way to hold several documents in one file. A converter that quietly drops these leaves you with a config that behaves differently. This one lists every change in the Notes panel and gives each dropped value its YAML path.
- Null values, including a key with nothing after the colon, are dropped, written as empty text or reported as an error, as you choose.
- Anchors and aliases are copied out in full, because TOML has nothing like
&nameand*name. - A file that is a list, or a single value, has no table to start from, so it is placed under a key you name. The default is items.
- Several documents separated by
---become an array of tables, or you can keep only the first. - A list that mixes types, such as [1, text, true], is valid TOML 1.0, but the Notes panel flags it because older TOML readers reject it.
- Comments are not carried over. The Notes panel says so when your YAML had any.
Convert alacritty.yml to alacritty.toml
Alacritty moved its config format from YAML to TOML, and many people search for how to convert alacritty yaml to toml. Paste your alacritty.yml and the structure is converted: nested maps become tables and key_bindings becomes an array of tables.
The same approach works for other tools that switched format, and for moving config into Rust, Hugo or Python projects that expect TOML, such as pyproject.toml.
Anchors, aliases and merge keys
YAML lets you define a block once with &defaults and reuse it with <<: *defaults. TOML has no such feature, so the converter writes the shared keys into every table that used them. This input has one null as well:
defaults: &defaults
adapter: postgres
pool: 5
timeout: null
development:
<<: *defaults
database: app_dev
production:
<<: *defaults
database: app_prod
pool: 20
replicas: [db1.internal, db2.internal][defaults]
adapter = "postgres"
pool = 5
[development]
adapter = "postgres"
pool = 5
database = "app_dev"
[production]
adapter = "postgres"
pool = 20
database = "app_prod"
replicas = ["db1.internal", "db2.internal"]The notes say 2 aliases and 2 merge keys were expanded and list the three timeout paths as dropped nulls. Production keeps its own pool: 20 because a key written beside << wins over the merged one. Turn off Apply merge keys to keep << as a plain key instead.
Several documents and top-level lists
A YAML file such as a Kubernetes manifest can hold many documents. TOML holds one, so by default they are written as an array of tables under the key items:
[[items]]
name = "api"
port = 8080
[[items]]
name = "worker"
port = 9090
[[items]]
name = "cron"
port = 9100Change Key for a top-level list if your program expects another name. Choose First document only to convert just the first one.
Options explained
- Null values: drop them and list the paths, write them as empty text, or stop with an error.
- Several documents: an array of tables, or the first document only.
- Sort keys: puts the keys of every table in alphabetical order. Off keeps the order of your YAML.
- Inline small objects: writes an object with up to three simple keys on one line, such as
padding = { x = 6, y = 6 }, instead of giving it a section. - Multi-line text blocks: text containing line breaks is written between triple quotes. Off writes one line with \n escapes.
- Date strings: keep 2026-11-07 as text, or write it as a TOML date. Only text in the exact date, time or date-time form is converted.
- YAML version: 1.2 reads yes and no as text. 1.1, the rules PyYAML follows, reads them as booleans and turns timestamps into dates. A date with no time becomes midnight UTC.
- Apply merge keys: copies anchored keys into the tables that use
<<. - Key for a top-level list: the name used when the YAML is a list, a single value or several documents.
YAML to TOML in Python
Python can read YAML with PyYAML and write TOML with tomli-w. Python 3.11 added tomllib, but it only reads TOML:
import yaml
import tomli_w
with open('config.yaml') as f:
data = yaml.safe_load(f)
with open('config.toml', 'wb') as f:
tomli_w.dump(data, f)TOML has no null, so remove None values from the data first. This page does that for you and lists what it removed. To go back, use TOML to YAML. To check the data in between, YAML to JSON and TOML to JSON show it as JSON, and JSON to TOML covers JSON input. If you want the keys in a fixed order before converting, Sort YAML Keys does that.
Limits
- Comments are not carried over. Add them to the TOML by hand afterwards.
- Null values cannot be stored. They are dropped, replaced or reported, as you choose, and always listed.
- Whole numbers outside the 64-bit range TOML allows are written as floats and may be rounded by the program that reads the TOML.
- Custom YAML tags are ignored and their values kept as plain data. Binary values become base64 text.
- A key that is not plain text, such as a list, is written as JSON text. Two keys that become the same text, such as 1 and "1", collapse into one and the later value wins.
- The tool checks that the TOML it writes follows the format, not that your program accepts the values. It cannot know which keys a given application expects.
- Large files take longer. Above about 150,000 characters, repeated keys in one block are not checked and the last value wins.
Your YAML is converted in your browser. It is not uploaded or stored. See the Privacy Policy for details.