YAML to TOML
Convert YAML configuration files to TOML format. Mappings become TOML tables, sequences become arrays, and scalar values are type-preserved.
Why Convert YAML to TOML?
TOML (Tom's Obvious, Minimal Language) was designed specifically for configuration files.
Unlike YAML, TOML is not whitespace-sensitive - it uses explicit section headers
([section]) rather than indentation for structure.
This makes it harder to introduce accidental bugs from indentation drift, and its
explicit typing means there is no ambiguity about whether a bare value is a string,
a boolean, or a number.
TOML is the native configuration format for Rust (Cargo.toml), Python packaging (pyproject.toml), the Hugo static site generator, the Mise/Rtx version manager, and many modern developer tools. Converting an existing YAML config to TOML is a common step when adopting one of these ecosystems.
YAML to TOML Mapping Rules
- Mappings become TOML tables. Nested mappings produce section headers:
[parent.child]. - Sequences of scalars become TOML arrays:
tags = ["developer", "designer"]. - Sequences of mappings become TOML arrays of tables:
[[dependencies]]. - Strings, integers, floats, and booleans map directly to TOML equivalents with no type coercion.
- Date values parsed from YAML (e.g.
2024-01-15) become TOML local date values. - Null values are omitted from the output - TOML has no null type. Keys whose YAML value is
nullare silently dropped.
TOML Limitations When Converting from YAML
No Null Values
TOML does not have a null type. Keys with null values in YAML are omitted from the TOML output. If a key must be present with an empty value, use an empty string ("") in your YAML before converting.
Homogeneous Arrays Only
TOML requires all elements of an array to have the same type. A YAML sequence mixing strings and numbers ([1, "hello"]) cannot be represented as a TOML array and will produce a conversion error.
No Comments
YAML comments do not survive the parse-reserialise cycle. If your YAML file has inline documentation comments, they will be absent from the TOML output. Add them back manually after converting.
Table Ordering Rules
TOML requires all scalar key-value pairs in a table to appear before any sub-table definitions. Deeply nested YAML that violates this ordering will cause a TOML serialisation error. Restructure the YAML to declare scalar values before nested mappings.
Common Use Cases
Rust Cargo.toml
Cargo.toml is the package manifest and dependency file for Rust projects. If you're starting from a dependency list in another format or migrating from a different build system, converting to TOML produces a starting point for the Cargo manifest.
Python pyproject.toml
The pyproject.toml format is the modern standard for Python project metadata, build configuration, and tool settings (Black, isort, mypy, etc.). Converting from a YAML setup.cfg equivalent is a common migration task.
Hugo Site Config
Hugo, the Go-based static site generator, supports YAML, TOML, and JSON for site configuration. TOML is the original default format. Converting a YAML Hugo config to TOML is useful when following TOML-based Hugo documentation or themes.
Mise / Rtx Tool Versions
Mise (formerly rtx) uses a TOML-based .mise.toml config file for managing tool versions and environment variables per project. Converting from a YAML-based .tool-versions equivalent simplifies the migration.