.TOML TOML Configuration
.toml

TOML Configuration

TOML maps configuration data to hash tables using explicit key-value syntax with native types for strings, integers, floats, booleans, datetimes, arrays, and tables. It is the config format for Rust (Cargo.toml) and Python (pyproject.toml).

Learn more ↓
Data layout
Header schema
Records structured data
Configuration Formatapplication/tomlUTF-8TOML v1.0Typed Values2013
By FileDex
Not convertible

Configuration format. Conversion between config formats requires semantic mapping.

Common questions

What is the difference between TOML and YAML for configuration?

TOML has explicit types with no implicit coercion — a value's type is always determined by its syntax. YAML silently converts unquoted strings like 'yes', 'no', and 'null' to booleans and null. TOML is designed for flat-to-moderately-nested configuration. YAML handles deeply nested structures better.

Why does Rust use TOML instead of JSON or YAML?

Cargo adopted TOML because it supports comments (JSON does not), has unambiguous types (YAML does not), and maps directly to Rust's type system. The lack of implicit coercion makes TOML safe to parse without surprising behavior, which matters for a build system processing untrusted package manifests.

How do I use arrays of tables in TOML?

Double-bracket headers ([[products]]) define arrays of tables. Each [[products]] section appends a new element to the array. This syntax represents what JSON would write as [{...}, {...}]. It is used in Cargo.toml for [[bin]], [[example]], and [[bench]] sections.

Does Python have built-in TOML support?

Python 3.11+ includes tomllib in the standard library for reading TOML files. For Python 3.7-3.10, use the tomli package (pip install tomli), which is the same code that became tomllib. For writing TOML, use the tomli-w package — tomllib is read-only.

What makes .TOML special

What is a TOML file?

TOML (Tom's Obvious, Minimal Language) is a configuration file format created by GitHub co-founder Tom Preston-Werner. It is designed to be minimal and unambiguous, mapping directly to a hash table. TOML is used as the configuration format for Rust (Cargo.toml), Python (pyproject.toml), and many other tools.

Continue reading — full technical deep dive

How to open TOML files

  • VS Code (Windows, macOS, Linux) — With Even Better TOML extension
  • Any text editor — TOML files are plain text
  • toml (Python) — pip install toml for parsing
  • toml-rs (Rust) — Native TOML parsing

Technical specifications

Property Value
Version TOML v1.0.0 (2021)
Encoding UTF-8
Data Types String, integer, float, boolean, datetime, array, table
Comments Hash (#) line comments
Nesting Dot-separated keys or [table] headers

Common use cases

  • Rust projects: Cargo.toml package configuration.
  • Python projects: pyproject.toml build configuration.
  • Go modules: go.mod companion configuration.
  • Static site generators: Hugo, Pelican configuration.

.TOML compared to alternatives

.TOML vs .YAML
Type safety
TOML has explicit, unambiguous types determined by syntax. YAML silently coerces unquoted 'yes', 'no', and numeric-looking strings to booleans and numbers, causing the Norwegian boolean problem.
 TOML wins
.TOML vs .YAML
Complex nesting
YAML handles deeply nested structures with simple indentation. TOML requires verbose dotted keys or repeated [section.subsection.deep] headers for deeply nested configs.
 YAML wins
.TOML vs .JSON
Human editability
TOML supports comments, bare string keys, multiline strings, and does not require trailing comma management. JSON requires double-quoted keys, no comments, and strict comma placement.
 TOML wins
.TOML vs .INI
Type system
TOML has native integers, floats, booleans, datetimes, arrays, and nested tables. INI files treat all values as untyped strings with no standard for arrays or nesting.
 TOML wins

Technical reference

MIME Type
application/toml
Developer
Tom Preston-Werner
Year Introduced
2013
Open Standard
Yes — View specification

Binary Structure

TOML is a text format with no binary structure. A TOML file consists of key-value pairs organized into tables. Top-level key-value pairs exist in the root table. Tables are declared with [table-name] headers, creating named sub-objects. Dotted keys (server.port = 8080) create implicit intermediate tables. Arrays of tables use [[array-name]] double-bracket headers, with each occurrence appending a new element. Keys can be bare (alphanumeric, dash, underscore), quoted with double quotes, or quoted with single quotes (literal). Values have explicit types: strings (basic with escapes or literal with no escapes), integers (decimal, hex 0x, octal 0o, binary 0b, with _ separators), floats (IEEE 754, including inf and nan), booleans (true/false, lowercase only), datetimes (RFC 3339 with optional timezone), local dates, local times, arrays (comma-separated in square brackets, typed but mixed types allowed), and inline tables ({key = value} on one line). Comments begin with # and extend to end of line. TOML is always encoded in UTF-8. Unlike YAML, TOML has no implicit type coercion — every value's type is determined unambiguously by its syntax.

2013Tom Preston-Werner (GitHub co-founder) publishes TOML as a minimal, unambiguous alternative to YAML and JSON for configuration2015Rust adopts TOML for Cargo.toml package manifests, giving TOML a major ecosystem anchor2016Hugo static site generator adopts TOML as its primary configuration format (alongside YAML and JSON)2019Python PEP 518 formalizes pyproject.toml as the standard build configuration file, replacing setup.cfg/setup.py2021TOML v1.0.0 specification published — first stable release after 8 years of development2024Go 1.22+ proposal to adopt go.toml under discussion; TOML gains broader cross-language adoption momentum
Validate and parse TOML with Python 3.11+ other 
python3 -c "import tomllib; tomllib.load(open('config.toml', 'rb')); print('Valid')"

Python 3.11 includes tomllib in the standard library for reading TOML. It raises tomllib.TOMLDecodeError with line/column info on invalid input. No pip install needed.

Convert TOML to JSON with Python other 
python3 -c "import tomllib, json, sys; print(json.dumps(tomllib.load(open(sys.argv[1],'rb')),indent=2,default=str))" config.toml

Parses the TOML file and outputs formatted JSON. The default=str argument handles datetime objects that are not JSON-serializable. Useful for piping into jq for further processing.

Query TOML values with taplo other 
taplo get -f config.toml 'package.version'

taplo is a TOML toolkit that validates, formats, and queries TOML files. The get subcommand extracts a value by dotted key path.

Format a TOML file with taplo other 
taplo format config.toml

Reformats the TOML file with consistent indentation, alignment, and whitespace. taplo follows the TOML v1.0 spec strictly and reports errors on invalid syntax.

Read TOML in a shell script using yq other 
yq -p toml -o json config.toml | jq '.database.port'

yq v4+ supports TOML input with -p toml flag. This converts the TOML to JSON and pipes it to jq for value extraction, enabling TOML querying in shell scripts.

TOML → JSON render lossy JSON is consumed natively by JavaScript applications and web APIs. Converting TOML configuration to JSON enables programmatic manipulation with jq, validation with JSON Schema, and import by tools that lack TOML parsers.
TOML → YAML render lossy Kubernetes, Docker Compose, and Ansible consume YAML configuration. Converting TOML-based configs to YAML enables integration with DevOps toolchains that standardize on YAML input.
TOML → ENV render lossy Twelve-factor applications and Docker containers expect configuration as environment variables. Flattening TOML key-value pairs to .env format enables deployment in containerized environments.
LOW

Attack Vectors

  • Denial of service via extremely large arrays or deeply nested inline tables — a crafted TOML file with millions of array elements can exhaust parser memory
  • Duplicate key exploitation — TOML forbids duplicate keys, but non-compliant parsers that accept duplicates may use inconsistent values, causing configuration logic errors

Mitigation: FileDex processes TOML files entirely in the browser as text. No execution of values, no external resource loading, no server-side parsing. TOML has no code execution mechanism in its specification.

taplo tool
TOML toolkit — validator, formatter, and language server with VS Code extension
tomllib library
Python 3.11+ standard library module for parsing TOML — no external dependencies
Rust TOML serialization/deserialization — the parser used by Cargo itself
BurntSushi/toml library
Go TOML library with full v1.0 spec compliance — used by Hugo and other Go tools
VS Code extension providing syntax highlighting, validation, and formatting for TOML files
tomli library
Python TOML parser for Python 3.7-3.10 — backport of the tomllib standard library module