TOML to YAML

The same settings, in the format the other tool wants

TOML and YAML are both configuration formats and they overlap almost completely, so converting between them is usually a matter of which tool you are feeding rather than which format is better. Rust and Python packaging chose TOML; Kubernetes, GitHub Actions and Docker Compose chose YAML. Sooner or later you have settings in one and need them in the other.

The conversion itself is unremarkable — tables become mappings, array-of-tables becomes a sequence of mappings, and the scalar types line up. What is worth being careful about is the small set of things that can go wrong quietly, and this page is built around those rather than around the easy 95%.

The first is numbers. TOML integers are 64-bit by specification, and a JavaScript number is a double that runs out of exact integers at 2^53. Put a 19-digit ICCID or a Twitter-style snowflake ID through a naive converter and it comes back rounded, with no error: 8901240544102066246 becomes 8901240544102066000. Here the digits are carried across as text and re-emitted as a bare YAML integer, so they survive.

The second is comments, and this page cannot save them. TOML config is heavily annotated and a converter has nowhere to put those annotations — the parser hands over values, not the text around them. Rather than let that pass unmentioned, the number of comments in your input is counted and reported under the output, so you know exactly how much explanation you are leaving behind. If you want to tidy a TOML file as TOML instead, the formatter keeps every one of them.

Nothing is uploaded. Configuration files hold registry tokens, connection strings and credentials, so the conversion happens in this tab.

Converting a file

1. Paste or upload the TOML – A whole Cargo.toml or pyproject.toml, a Netlify or Hugo config, or a fragment. Invalid input is reported with the line and column from the parser, so you can fix it rather than guess.
2. Pick an indent – Two spaces is what almost everything in the YAML world uses, including Kubernetes manifests and GitHub Actions workflows. Four is available if a house style calls for it. Tabs are not offered because YAML forbids them for indentation, which is the single most common YAML mistake there is.
3. Check the comment count – If your input had comments, a note under the output says how many did not come across. That is not a failure to fix — it is a fact about converting between formats, and it is better said out loud than discovered later.
4. Copy it, or check it first – Paste the result into YAML Validator if it is going somewhere strict, or into YAML to Table to see the array-of-tables sections as a grid.

Watch what happens to a version string. In TOML, version = "2.4.1" is quoted and stays a string. Convert it, and a value like 1.20 that somebody wrote unquoted as a TOML float arrives in YAML as the number 1.2 — the trailing zero is gone, because it was never a string in the first place. That is TOML behaving correctly and it still breaks a version comparison downstream. If a value is a version, quote it at the source.

A provisioning config, moved to YAML

The parts worth watching are the ICCID and the array-of-tables. A 19-digit integer is past what a JavaScript number holds exactly, and [[subscriber]] has to become a YAML sequence rather than a repeated key.

[[subscriber]]
imsi = "234151234567890"
iccid = 8901240544102066246

[[subscriber]]
imsi = "234159876543210"
iccid = 8901240544102066247

subscriber:
  - imsi: '234151234567890'
    iccid: 8901240544102066246
  - imsi: '234159876543210'
    iccid: 8901240544102066247

# every digit intact. a naive
# converter gives ...066000

What people use it for

Feeding a tool that only reads YAML

You have settings in a pyproject.toml and a pipeline that wants them as YAML, or the other way round. The values are the same; only the syntax has to change. This is the bulk of the traffic to a page like this, and it is genuinely boring — which is the point.

Comparing two configs written in different formats

A service is configured in TOML for local development and YAML in the cluster, and they have drifted. Converting one and diffing is far quicker than reading both. TOML to JSON and YAML to JSON are the other way to do it — normalise both to JSON and compare that.

Getting a config into a Kubernetes ConfigMap

A ConfigMap holds YAML, and plenty of applications ship their defaults as TOML. Convert, indent it under the right key, and if the value has to go into a Secret rather than a ConfigMap, YAML to Base64 is the next step.

Learning what a TOML file actually contains

Array-of-tables is the part of TOML that trips people up — [[subscriber]] repeated three times is one array of three records, not three sections. Seeing it as a YAML sequence makes the structure obvious in a way reading the TOML does not, particularly if YAML is the format you think in.

What it handles

• Integers past 2^53 stay exact. A 19-digit ICCID or account reference keeps every digit instead of being rounded by a JavaScript number.
• Array-of-tables becomes a sequence. Repeated [[table]] sections come out as a proper YAML list of mappings.
• TOML dates are carried across. Offset datetimes, local dates and local times each keep their own shape.
• Comment loss is reported, not hidden. The count of comments left behind is shown under the output.
• Parse errors name the line and column, taken from the parser rather than guessed at.
• Nothing is uploaded. The file stays in this tab.

Questions that come up

Why are my comments gone?

Because a converter reads values, and a comment is not a value. The parser produces a tree of settings with no record of the text that sat beside them, so there is nothing to carry across even in principle — a comment against a TOML key has no obvious home in the YAML output. This page counts them and tells you. If what you actually wanted was a tidier TOML file rather than YAML, the TOML formatter keeps every comment exactly where it was.

Will my long ID numbers survive?

Yes, and this is the one thing most converters get wrong. TOML specifies 64-bit integers while a JavaScript number is an IEEE-754 double, exact only to about 15 digits. Anything longer is silently rounded by a naive conversion. Here the digits are carried as text and written back as a bare YAML integer, so 8901240544102066246 arrives intact rather than as 8901240544102066000.

What happens to TOML dates?

They come across as YAML timestamps. TOML has three separate date types — an offset datetime, a local date, and a local time — and each keeps its shape rather than all collapsing into one. YAML understands timestamps natively, so nothing needs quoting.

Is the output valid YAML?

It is emitted by js-yaml, which quotes anything that would otherwise be misread, and indentation is spaces only. Run it through YAML Validator if you want that confirmed independently before it goes anywhere.

Can I go back the other way?

YAML to TOML does the reverse, and it has one restriction worth knowing before you rely on a round trip: TOML has no null. A YAML key with no value cannot be represented at all, so those keys are dropped and named. Everything else comes back.

Which format should I be using?

Usually neither answer is yours to make — the tool decides. Where you do have a choice, the useful split is that TOML is unambiguous and flat, and YAML is compact and expressive but has more ways to surprise you. The comparison post works through the actual failure modes of each rather than the syntax.

Related tools

Worth reading

• TOML v1.0.0 — the specification – Short, readable, and explicit that integers are 64-bit
• YAML 1.2.2 — the specification – Including the indentation rules that make tabs illegal