TOML File Format (.toml)
A TOML file holds configuration as key-value pairs grouped into tables, with native types for strings, integers, floats, booleans, arrays and dates.
TOML at a glance#
| Full name | Tom's Obvious Minimal Language |
|---|---|
| File extension | .toml |
| Category | Data Files |
| Developer | Tom Preston-Werner |
| First released | 2013 |
| MIME types | application/toml |
| Compression | Uncompressed |
| Specification | TOML v1.1.0 |
| FileFlip support | FileFlip reads and writes this format |
What a .toml file can hold#
These are the things a TOML file either supports or does not, and they are what decides whether a conversion keeps everything or quietly drops something.
| Human readable | Yes |
|---|---|
| Comments | Yes |
Strengths and limitations of TOML#
What TOML does well
- Every value has an explicit type, including dates and times, with no string-versus-number guessing
- Every valid TOML document maps to exactly one hash table, so there's no ambiguity about how to read it
- Comments and table headers keep long configuration files organized without extra tooling
Where TOML falls short
- A document has to start with a table, so a bare list of items at the top level has nowhere to go
- Deeply nested data gets verbose fast, since each nesting level needs its own table header
- Far fewer parsers and less tooling exist for it than for JSON or YAML
- No schema language exists for it the way JSON Schema exists for JSON
Pick TOML for configuration files a person writes and re-reads by hand, where explicit types and unambiguous structure matter more than deep nesting.
Convert TOML to JSON or YAML when the data needs to nest more than a couple of levels deep, or when the tool consuming it doesn't have a TOML parser.
How to open a .toml file#
A .toml file opens in the programs below, grouped by the platform you are on. If you would rather not install anything, FileFlip converts TOML into a format your machine already opens, and it does it in the browser tab rather than on a server.
| Platform | Programs that open it |
|---|---|
| Windows | VS Code, Notepad++, Sublime Text |
| macOS | VS Code, Sublime Text, TextEdit |
| Linux | VS Code, vim, gedit |
| Web | FileFlip |
TOML questions people ask#
Why can't I convert a TOML file to a JSON array?
A TOML document always starts as a table of key-value pairs, so a file that only needs to model a top-level list, like a plain array of strings, doesn't fit TOML's grammar at all. Converting a JSON array to TOML has to wrap the array under a key, like items = [...], because TOML has no bare top-level list.
Does TOML support comments?
Yes. TOML comments start with a hash character and run to the end of the line, the same as YAML and Python. That's one of the reasons TOML was picked for Cargo.toml and pyproject.toml over JSON, which has no comment syntax at all.
What happens to TOML's dates when converting to JSON?
TOML has a native date-time type with its own syntax, and JSON has none, so converting to JSON turns every TOML date into a plain string. Which string format it becomes depends on the converter, since JSON doesn't specify one either.
Converting TOML files#
Convert TOML to another format
Convert another format to TOML
Every conversion runs inside your browser. The file is read from your disk, the work happens on your own machine, and nothing is uploaded. How FileFlip works names the engine behind each family and how to verify that for yourself.