What does a YAML to TOML converter do?
YAML and TOML are both human-friendly configuration formats, and they can represent the same data: strings, numbers, booleans, dates, lists and nested maps. They write that data very differently. YAML builds structure with indentation. TOML builds it with section headers ([table], [[array]]) and key = value lines that never depend on whitespace. A YAML to TOML converter parses one format into a data tree and writes the tree back out using the other format’s rules.
This tool works both ways. Paste YAML and click To TOML, or paste TOML and click To YAML. It looks at your input as you type and moves the Ctrl+Enter shortcut to the direction that makes sense, so you rarely need the mouse. Parsing and writing both happen locally in your browser. Nothing is uploaded.
YAML (“YAML Ain’t Markup Language”, 2001) is the format behind Kubernetes manifests, Docker Compose, GitHub Actions, Ansible and OpenAPI. TOML (“Tom’s Obvious Minimal Language”, created by GitHub co-founder Tom Preston-Werner, v1.0 in 2021) is the format behind Rust’s Cargo.toml, Python’s pyproject.toml, Hugo, Netlify, Poetry and many CLI tools.
How to convert YAML to TOML
- Paste your YAML (or TOML) into the input box.
- Press
Ctrl+Enteror click To TOML / To YAML. The highlighted button is the oneCtrl+Enterruns. - Read any
# Note:lines at the top of the output. They list values TOML can’t represent, such as nulls. - Copy the result with the Copy button or
Ctrl+Shift+C.Ctrl+Lclears the input.
Errors show the line number and the reason, for example YAML line 12: duplicate key "image" or TOML line 4: table [server] is defined twice. That makes the converter a quick syntax check for either format.
How YAML structures map to TOML
| YAML | TOML output | Example |
|---|---|---|
Top-level key: value | Plain key = value lines at the top | title = "My Site" |
| Nested mapping | [table] section (or [a.b] for deeper levels) | [params.social] |
| List of mappings | One [[array-of-tables]] block per item | [[menus.main]] |
| List of scalars | Inline array (multi-line when longer than 80 characters) | tags = ["go", "rust"] |
| Mapping inside a list of scalars | Inline table | { name = "a", port = 80 } |
| or > block string | """ multi-line string | run = """ ... """ |
Unquoted date 2026-10-24 | TOML local date, not a string | released = 2026-10-24 |
null / ~ | Left out, with a # Note: | — |
Here is a Hugo site config converted from hugo.yaml to hugo.toml, a common migration because Hugo reads either:
baseURL: https://example.org/
title: My Site
params:
description: A fast static site
social:
github: example
menus:
main:
- name: Blog
url: /blog/
weight: 10
- name: About
url: /about/
weight: 20
baseURL = "https://example.org/"
title = "My Site"
[params]
description = "A fast static site"
[params.social]
github = "example"
[[menus.main]]
name = "Blog"
url = "/blog/"
weight = 10
[[menus.main]]
name = "About"
url = "/about/"
weight = 20
Notice that menus gets no header of its own. A table that only contains other tables doesn’t need one, because [[menus.main]] creates it implicitly. The converter also writes every plain key of a table before its sub-tables. In TOML, a key written after a [header] belongs to that header, so a naive converter that keeps the YAML key order can silently move keys into the wrong table.
Converting TOML to YAML (pyproject.toml, Cargo.toml)
The other direction is useful when a tool or pipeline only accepts YAML, or when you want to read a big TOML file as an indented tree. A pyproject.toml with a multi-line dependency array:
[project]
name = "acme"
version = "0.4.0"
requires-python = ">=3.10"
dependencies = [
"httpx>=0.27",
"pydantic>=2.6",
]
[tool.ruff]
line-length = 100
becomes:
project:
name: acme
version: "0.4.0"
requires-python: ">=3.10"
dependencies:
- httpx>=0.27
- pydantic>=2.6
tool:
ruff:
line-length: 100
"0.4.0" and ">=3.10" stay quoted. An unquoted >=3.10 would start a YAML folded block, and version-like strings are quoted so no YAML loader reads them as numbers. Cargo-style inline tables such as serde = { version = "1.0", features = ["derive"] } turn into nested mappings, and [[bin]] arrays of tables turn into lists of mappings.
Type differences and common conversion errors
Most surprises in YAML ↔ TOML conversion come from types, not syntax:
- No null in TOML.
timeout: nullortimeout: ~has no TOML equivalent, so the key is left out and listed in a# Note:. Nulls inside lists are left out of the list the same way. - The “Norway problem”. YAML 1.1 parsers read unquoted
no,yes,onandoffas booleans, so a country codeNObecamefalse. This converter follows YAML 1.2 and keeps them as strings. TOML only knowstrueandfalse. Going TOML → YAML, the tool quotes such strings so older YAML loaders can’t flip them. - Floats that look like versions. Unquoted
version: 1.10is the float 1.1 in YAML, and it comes out as1.1. Quote version numbers. Unquoted1.0stays a float (1.0), not the integer1. - Leading zeros.
zip: 01234is kept as the string"01234"instead of being turned into a number with digits lost. - Dates and times. An unquoted
2026-10-24or2026-10-24T09:30:00Zbecomes a real TOML date/date-time. A quoted one stays a string. TOML local times like07:32:00are quoted in YAML output because YAML 1.1 would read them as base-60 numbers. - Big integers. 64-bit IDs such as
9007199254740993keep every digit in both directions. JavaScript numbers would normally round them. - Anchors and merge keys.
&defaults,*defaultsand<<: *defaultsare expanded. TOML has no references, so shared blocks are repeated in full. - Top-level lists. A TOML document is always a table. If your YAML starts with
- item, put it under a key first (items:). - Multiple documents. A YAML stream separated by
---holds several documents. TOML holds one, so convert them one at a time. - Comments. Neither direction keeps comments. The parsers don’t keep them in the data tree, so copy important comments across by hand.
- Tabs. YAML forbids tabs for indentation, and you’ll get an error that points at the line.
TOML is stricter than YAML, and the TOML parser reports these TOML 1.0 rules: a [table] can’t be defined twice, a key can’t be set twice, inline tables { ... } must fit on one line and can’t be extended later, and a static array x = [...] can’t be extended with [[x]].
YAML vs TOML comparison
| Feature | YAML | TOML |
|---|---|---|
| Structure | Indentation | [table] headers and key = value |
| Deep nesting | Compact | Verbose ([a.b.c] headers) |
| Lists of objects | - key: value items | [[array-of-tables]] blocks |
| Booleans | true/false (YAML 1.1 also yes/no/on/off) | true/false only |
| Null | null, ~ or empty | Not supported |
| Dates | Timestamps (loader-dependent) | First-class date, time and date-time types |
| Multi-line strings | Literal and folded block scalars | """ and ''' strings |
| References | Anchors, aliases, merge keys | None |
| Whitespace-sensitive | Yes | No |
| Typical use | Kubernetes, Compose, CI pipelines, Ansible | Cargo, pyproject.toml, Hugo, CLI configs |
Choose TOML for flat-to-moderate configs that people edit by hand. There’s no indentation to break and no implicit type guessing. Choose YAML for deeply nested data, long lists of objects, or when the ecosystem requires it. If you also need JSON, the JSON ↔ YAML converter handles that leg. Run the result through the YAML validator before you commit it.