--- url: https://findutils.com/guides/yaml-to-toml title: "How to Convert YAML to TOML (and Back)" description: "Convert YAML config to TOML 1.0 and TOML back to YAML. Read how mappings become tables, how lists become arrays of tables, and what happens to nulls and comments." category: developer content_type: guide guide_type: subtopic cluster: config locale: en read_time: 8 status: published author: "olgunozoktas" published_at: 2026-09-16T12:00:00Z excerpt: "TOML has no null and no top-level list, and YAML has both. Read which shapes convert cleanly, what the nulls setting actually changes, and why anchors are expanded rather than preserved." tag_ids: ["config", "yaml", "toml", "data-conversion"] tags: ["Config", "YAML", "TOML", "Data Conversion"] primary_keyword: "convert yaml to toml" secondary_keywords: ["yaml to toml converter", "toml to yaml", "yaml to cargo toml", "yaml to pyproject toml", "hugo config yaml to toml"] tool_tag: "yaml-toml-converter" related_tool: "yaml-toml-converter" related_tools: ["yaml-toml-converter", "json-yaml-converter", "json-toml-converter", "yaml-validator", "env-yaml-converter"] og_image: "/images/content/guides/yaml-to-toml-cover-20260916.webp" image_alt: "Blank pastel paper strips arranged in an indented staircase beside a brass tray holding the same strips in flat, evenly divided rows." updated_at: "2026-09-16T12:00:00Z" --- Convert YAML to TOML when a settings file has to move into a Rust `Cargo.toml`, a Python `pyproject.toml`, or a Hugo or Zola `config.toml`. FindUtils [YAML TOML Converter](/developers/yaml-toml-converter/) reads one format and writes the other in the browser, in one step rather than a detour through JSON on two pages. This guide explains which shapes map cleanly between the two formats, what the nulls setting changes, why anchors are expanded, and what neither direction preserves. ## Why Not Just Chain Two JSON Converters? Because it costs two pastes and loses information. The usual workaround is YAML to JSON on one page, then JSON to TOML on another. That works for plain strings and numbers, and it quietly damages two things. - **Dates.** JSON has no date type. A YAML `2026-01-01` becomes a quoted string in JSON, and arrives in TOML as a string rather than a TOML date. - **The paste count.** A config with credentials in it goes into two separate forms instead of one. Converting directly keeps dates as dates and halves the handling. ## What Maps Cleanly Between YAML and TOML? The structural mapping is straightforward, and the table below is the whole of it. | YAML | TOML | |---|---| | Mapping | Table, written as `[name]` | | List of mappings | Array of tables, written as `[[name]]` | | List of scalars | Inline array on one line | | String, number, boolean | The same, typed | | Date or timestamp | TOML date or datetime, not a quoted string | | Null | **No equivalent** — see below | So this YAML: ```yaml title: Demo database: host: db.internal port: 5432 services: - name: web port: 80 - name: api port: 3000 ``` becomes: ```toml title = "Demo" [database] host = "db.internal" port = 5432 [[services]] name = "web" port = 80 [[services]] name = "api" port = 3000 ``` ## Why Must the YAML Root Be a Mapping? Because a TOML document is a table at the top level, and TOML has no syntax for a bare list. A YAML file that starts with a sequence has nowhere to go. ```yaml - first - second ``` That is refused with the reason rather than wrapped in an invented key such as `items`. Naming the key is your decision — whatever reads the TOML will look for a specific name, and a converter guessing it produces a file that parses and still fails. ## What Does the Nulls Setting Actually Change? TOML has no null. There is no way to write "this key exists and has no value", so the converter makes you choose and then tells you what it did. - **Drop** (the default) leaves the key out of the TOML entirely. - **Empty string** writes `key = ""` instead. Either way, every affected path is listed under the panels. That matters because the two options mean different things to the program reading the file: a missing key usually falls back to a default, while an empty string is often a value that overrides one. ## What Happens to Anchors and Merge Keys? They are resolved when the YAML is read, so the TOML holds the real values written out in full. YAML lets you define a block once and reuse it: ```yaml defaults: &base restart: always worker: <<: *base image: node:22-alpine ``` TOML has no way to reference another table, so `worker` is written with `restart = "always"` spelled out. This is worth knowing before converting a Docker Compose or GitLab CI file, where merge keys are common: the TOML will be longer than the YAML, and the shared block is no longer shared. Your YAML file keeps its anchors — only the conversion expands them. ## What Is Not Preserved? Three things, in both directions. - **Comments.** Both sides read data and write data. If the comments carry meaning, keep the original file and treat the converted one as a starting point. - **Key order beyond the input order.** Keys are written in the order they arrived unless you turn on alphabetical sorting. - **Multiple documents.** A YAML file with several documents separated by `---` converts the first one. TOML has no concept of several documents in one file, and merging them would need rules this tool does not invent. ## Is Anything Uploaded? No. Both parsers run in your browser and no request carries the document. The page loads analytics and advertising scripts like the rest of the site; your config is not part of that traffic. ## Common Mistakes ### Mistake 1: Converting a Multi-Document Kubernetes File A manifest bundle separated by `---` loses everything after the first document. Split it first, or convert each document separately. ### Mistake 2: Expecting Comments to Survive A heavily commented `config.yml` becomes a bare TOML file. Copy the comments across by hand if they matter. ### Mistake 3: Ignoring the Dropped-Null Report A key that vanishes is easy to miss in a long file. The report lists every path — read it before committing the result. ### Mistake 4: Assuming Anchors Stay Shared After conversion, editing the original block no longer changes the places that used it, because each one now holds its own copy. ### Mistake 5: Quoting a Date You Meant as Text `version: 2026-01-01` is a date to YAML and becomes a TOML date. Quote it in the source if you meant a string. ## Tools Used in This Guide - **[YAML TOML Converter](/developers/yaml-toml-converter/)** — Convert YAML to TOML 1.0 and back - **[JSON YAML Converter](/developers/json-yaml-converter/)** — The JSON side of the same triangle - **[JSON TOML Converter](/developers/json-toml-converter/)** — The other JSON side - **[YAML Validator](/developers/yaml-validator/)** — Check a YAML document parses before converting it - **[Env YAML Converter](/developers/env-yaml-converter/)** — Turn a `.env` file into a YAML map ## FAQ **Q: Is the YAML to TOML converter free?** A: Yes. It is free, needs no signup, and has no usage limits. Both parsers run in your browser. **Q: Which TOML version does it write?** A: TOML 1.0, including tables, arrays of tables, inline arrays, and dates and datetimes. **Q: Can it convert a docker-compose.yml to TOML?** A: Structurally yes, and the result is valid TOML. It will not be useful to Docker, which reads YAML — converting a Compose file is a reading or migration exercise, not a way to run it. **Q: What happens to a YAML timestamp?** A: It becomes a TOML datetime rather than a quoted string, which is one of the reasons to convert directly instead of chaining through JSON. **Q: Why is my converted file longer than the original?** A: Most likely anchors. A block reused in three places with `<<` is written out three times, because TOML cannot reference another table. **Q: Does it preserve comments?** A: No, in either direction. Keep the original file if the comments matter. ## Next Steps - Need the JSON side? Use the [JSON YAML Converter](/developers/json-yaml-converter/) or [JSON TOML Converter](/developers/json-toml-converter/). - Checking a document first? The [YAML Validator](/developers/yaml-validator/) reports the line and column. - Working with a `.env` instead? Read the [Env YAML Converter](/developers/env-yaml-converter/).