Why TOML Is Becoming the Preferred Config Format Over JSON and YAML

What is TOML?

TOML stands for Tom's Obvious Minimal Language , created by GitHub co‑founder Tom Preston‑Werner to be obvious and minimal. Its design goal is to let even non‑programmers read and edit configuration files at a glance without making mistakes.

It aims for a human‑friendly syntax similar to classic INI files while retaining clear structure.

Why JSON and YAML "fell out of favor"

JSON

JSON is machine‑friendly but human‑unfriendly: it relies on many braces, quotes, and a strict rule that the last line cannot end with a comma. Missing a single punctuation mark can break the entire program.

{
  "global": {
    "cache-dir": "D:\\Programs\\Python\\Python36\\pipcache",
    "timeout": 6000,
    "index-url": "http://mirrors.aliyun.com/pypi/simple/"
  },
  "install": {
    "trusted-host": "mirrors.aliyun.com"
  }
}

YAML

YAML looks nice to humans but is extremely sensitive to whitespace. A single extra or missing space can corrupt the configuration, making errors hard to locate.

global:
  cache-dir: D:\Programs\Python\Python36\pipcache
  timeout: 6000
  index-url: http://mirrors.aliyun.com/pypi/simple/
install:
  trusted-host: mirrors.aliyun.com

How TOML combines the best of both worlds

TOML offers JSON‑like logical clarity together with the familiar, simple style of Windows‑era INI files.

[global]
cache-dir = "D:\\Programs\\Python\\Python36\\pipcache"
timeout = 6000
index-url = "http://mirrors.aliyun.com/pypi/simple/"

[install]
trusted-host = "mirrors.aliyun.com"

Reading TOML in Python

Starting with Python 3.11, the standard library includes the tomllib module, so no extra package installation is required.

import tomllib

def read_toml_config(filepath="config.toml"):
    with open(filepath, "rb") as f:
        data = tomllib.load(f)
    return data

config_data = read_toml_config("pyproject.toml")
print(f"Cache dir: {config_data['global']['cache-dir']}")
print(f"Timeout: {config_data['global']['timeout']}")

Why major open‑source ecosystems adopt TOML

Python community

The pyproject.toml file now consolidates what used to be spread across setup.py and requirements.txt, becoming the single source of truth for builds and dependencies.

Rust community

Rust’s package manager Cargo uses Cargo.toml as its manifest format from day one, reflecting the language’s emphasis on rigor.

DevOps

Container tools, CI/CD pipelines, and other infrastructure configurations increasingly adopt TOML to reduce human‑induced errors and simplify editing.

Should you switch to TOML?

If your configuration is only a few lines, JSON works fine. For deeply nested structures that never need manual edits, YAML can suffice. However, for modern projects that want readable, safe, and maintainable configs—especially in 2026—switching to TOML is strongly recommended.