Key facts
- Plain UTF-8 text; the current stable specification is TOML 1.0.0 (2021).
- Values are typed: strings must be quoted, and integers, floats, booleans, dates/times, arrays and tables are distinct types.
- [table] headers create sections, [[array.of.tables]] creates lists of tables, and dotted keys (a.b = 1) create nested tables.
- MIME type application/toml; files are usually a few hundred bytes to a few KB.
How to open a .toml file
Windows
Open it in VS Code (add the Even Better TOML extension for validation) or Notepad++. Notepad works for quick edits.
macOS
Edit in VS Code, BBEdit or any text editor. With Python 3.11+, validate it in Terminal: python3 -c "import tomllib,sys; tomllib.load(open(sys.argv[1],'rb'))" pyproject.toml.
Linux
Edit with nano, vim or VS Code, and validate with the same python3 tomllib one-liner; no output means the file parsed successfully.
Common problems and fixes
- Duplicate key or 'table defined more than once' error
- TOML forbids defining the same key or [table] twice. Merge the duplicate sections into one, and check dotted keys are not redefining an existing table.
- Invalid value / expected a string
- Unlike INI, unquoted text is not a string in TOML. Wrap text in double quotes (name = "app") and use true/false in lower case for booleans.
- Inline table spans several lines and fails to parse
- TOML 1.0 requires inline tables { ... } to stay on one line with no trailing comma. Rewrite them as a normal [table] section if they are long.
- Tool ignores my settings
- The keys are under the wrong table, e.g. [tool.black] in pyproject.toml or [dependencies] in Cargo.toml. Check the tool's documentation for the exact section name.
Often converted to or from: JSON, YAML, INI, requirements.txt (dependencies)