THE FILE FIELD GUIDE

.toml

TOML Config

Web & Development

TOML describes settings with keys, values and table headers. It has typed values and prohibits duplicate key definitions. Its resemblance to INI does not imply identical syntax.

What it is used for: Typed key/value and table-based settings
What the file contains: Text

All sections, questions and sources

Content reviewed：2026-10-12 · Editor：Kai

Opening steps

Choose your environment or purpose to see its steps.

Editor: inspect the structure

Make a copy before saving.

Open in an editor such as VS Code and select the appropriate language mode.
Inspect keys/values, table headings, arrays and quoting.
Inspect encoding and line endings and avoid saving as rich text.

Syntax: use a TOML parser

Use the specification supported by the consumer.

Parse a copy with the application’s checker or compatible parser.
Inspect duplicate keys, table redefinitions and unclosed strings.
Inspect types/hierarchy and validate required keys after syntax passes.

Project settings: pyproject and similar files

Separate TOML syntax from tool-specific keys.

Consult the tool’s required tables and keys.
Apply a small change to a copy and run the tool’s checks/tests.
Inspect dependencies and build results against intent.

Menu labels and support vary by app, OS and version. Preserve the original before making changes.

Troubleshooting by symptom

Duplicate-key error: inspect collisions within tables and table redefinitions.
String error: review quotes/escapes, including backslashes in Windows paths.
Ignored setting: check table placement and whether the value has the intended type.
Duplicate-key error: inspect repeated definitions within the table.
Number parsed as text: inspect quotes and required type.
Only newer syntax fails: check the consumer’s supported TOML version.

TOML → JSON / another settings format

Inspect typed values/tables with a compatible parser and map destination settings.
Export separately and compare dates, arrays and nested tables.
Compare keys, record counts and types before/after conversion and document unsupported items.

Date/time types and comments may not have equivalent destination representations.

Reading tables and strings

Keys under a table heading belong to that table. Inspect hierarchy for dotted keys and arrays of tables.

Valid TOML syntax does not make an unknown tool-specific key effective.

title = "example"
[server]
port = 8080
enabled = true

Source for these steps：TOML Project · TOML v1.0.0 / Python Software Foundation · tomllib — Parse TOML files

Checking conversions and automatic saves

Comments, ordering and date types can change during conversion/resaving; assess required values separately from readability.

Avoid sending configuration containing keys/tokens to public repositories or validators.

Source for these steps：TOML Project · TOML v1.0.0 / Python Software Foundation · tomllib — Parse TOML files

Related-format differences

Related-format differences
Format	Main role	Selection notes
TOML	Typed configuration	Inspect tables and duplicates
INI	Application-dependent configuration	Typing rules are not universal
JSON	Structured data	Comment handling differs

Handling and security

Check credentials and private paths before sharing. Settings can alter connections/behavior; review unfamiliar configurations before applying them.

Questions and answers

Can a later duplicate key override an earlier one?

TOML does not permit duplicate definitions.

Can INI just be renamed TOML?

No; syntax/types require actual conversion.

Do all applications understand the same TOML keys?

No; key semantics are application-specific.

Is TOML the same as INI?

They look similar but differ in typing, arrays, hierarchy and syntax.

Do all pyproject.toml files use the same keys?

Standard and tool-specific tables can coexist; consult the consuming tool.

Format facts: name, steward and MIME type

Formal name: Tom’s Obvious, Minimal Language
Steward / specification: TOML project
MIME type: Depends on the producer or server; an extension alone does not establish a MIME type.

Primary and official sources

StandardTOML v1.0.0
Published specification for keys, tables and value types.
TOML Project · Link checked：2026-10-12
StandardRFC 8259 — JSON
Defines JSON syntax and interoperability considerations.
IETF / RFC Editor · Link checked：2026-10-08
Project documentationtomllib — Parse TOML files
Parsed TOML types and syntax errors.
Python Software Foundation · Link checked：2026-10-12