TOML to YAML Converter

Understanding TOML and YAML

TOML (Tom's Obvious, Minimal Language) is a configuration file format that emphasizes clarity and minimal syntax. It uses square-bracket table headers, dotted key paths, and explicit typing for strings, integers, floats, booleans, and dates. TOML is the native configuration format for Rust's Cargo package manager, Python's pyproject.toml (used by Poetry, pip, and setuptools), and the Hugo static site generator. For a complete reference on TOML syntax and semantics, visit our TOML guide.

YAML (YAML Ain't Markup Language) is a human-friendly data serialization format that uses indentation to express hierarchy. It supports mappings (key-value pairs), sequences (lists), and scalars (strings, numbers, booleans, null). YAML is the dominant configuration format in the DevOps ecosystem, powering Kubernetes manifests, Docker Compose files, GitHub Actions workflows, Ansible playbooks, and Helm charts. To explore YAML anchors, multi-line strings, and common pitfalls, see our YAML guide.

Both TOML and YAML are popular configuration formats, but they serve different ecosystems. TOML is favored in the Rust and Python communities for its strict typing and unambiguous syntax, while YAML dominates in DevOps and cloud-native tooling. Converting between them is a common task when migrating projects or integrating tools from different ecosystems.

Why Convert TOML to YAML?

There are several practical scenarios where converting TOML configuration to YAML is essential:

• Migrating Cargo or Hugo configs to YAML-based tools. When moving a Rust project's metadata into a CI/CD pipeline (GitHub Actions, GitLab CI) or converting a Hugo site's configuration to a YAML-first static site generator like Jekyll or Eleventy, TOML-to-YAML conversion is the first step.
• Converting between configuration format ecosystems. Teams that standardize on YAML for all configuration (Kubernetes, Docker, Ansible) may need to convert TOML-authored settings from Python or Rust projects into the same format for consistency and tooling compatibility.
• Generating Kubernetes or Docker Compose manifests from TOML data. If application metadata is defined in TOML (such as service names, ports, environment variables), converting it to YAML enables direct use in Kubernetes Deployments, Services, or Docker Compose stacks.
• Sharing configuration with teams that prefer YAML. YAML's widespread adoption means many developers are more familiar with its syntax. Converting TOML to YAML can reduce friction when onboarding team members or sharing configuration across organizations.

How the Conversion Works

TOML-to-YAML is a cross-format conversion that uses JSON as an intermediate representation. The syntax mapping between the two formats is remarkably clean:

1. Parse the TOML input using smol-toml, which validates the document against the TOML specification and extracts typed values.
2. Convert to JSON intermediate. TOML tables become JSON objects, arrays of tables become JSON arrays, and scalar values are mapped to their JSON equivalents. TOML date/time values are converted to ISO 8601 strings.
3. Serialize JSON to YAML using js-yaml, which produces properly indented YAML output with appropriate scalar styles (plain, quoted, block) based on the content.
4. Apply formatting options such as indentation level and flow vs. block style based on user preferences.

The table below shows how TOML constructs map to their YAML equivalents:

Before and After Example

Below is a practical example showing a TOML configuration file (similar to a Cargo.toml or Hugo config) and its YAML equivalent after conversion.

[package]
name = "my-service"
version = "0.3.1"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.37", features = ["full"] }

[server]
host = "0.0.0.0"
port = 3000
workers = 4
debug = false

[[server.routes]]
path = "/health"
handler = "health_check"

[[server.routes]]
path = "/api/data"
handler = "get_data"

package:
  name: my-service
  version: 0.3.1
  edition: "2021"

dependencies:
  serde:
    version: "1.0"
    features:
      - derive
  tokio:
    version: "1.37"
    features:
      - full

server:
  host: 0.0.0.0
  port: 3000
  workers: 4
  debug: false
  routes:
    - path: /health
      handler: health_check
    - path: /api/data
      handler: get_data

Notice the clear syntax mapping: TOML tables become YAML mappings with indentation, inline tables expand to nested mappings, and arrays of tables ([[server.routes]]) become YAML sequences of mappings. The structure is preserved faithfully while the syntax shifts to YAML conventions.

Tips and Best Practices

Related Tools

Explore other converters and resources that complement TOML-to-YAML conversion: