ConvertCSV

Converter tool

TOML to CSV Converter

Convert TOML arrays of tables and inline table lists into CSV

Preview

Output Preview

No output yet. Upload or paste input and convert.

TOML to CSV Converter

TOML is common in packaging and deployment files, and a list of records is often written as an array of tables. This TOML to CSV converter reads a file made of [[name]] blocks, or a single top-level array of inline tables, and writes one CSV row per entry. It is meant for flat record lists exported from tools or written by hand, not for reading an entire configuration file.

The parser is written for this page and handles a documented subset of TOML 1.0. Anything outside that subset is rejected with an error, so you never get a CSV that silently dropped data. Parse errors name a line; record-set and top-level key errors name the array or key instead.

Key features

  • Reads [[name]] arrays of tables and top-level arrays of inline tables, including multi-line arrays.
  • Columns are the union of keys across records, in first-seen order.
  • Basic strings with escapes (\n, \t, \", \\, \uXXXX) and literal strings are decoded.
  • Inline tables and arrays become JSON text in their cell, so nested data stays readable.

About the TOML to CSV format

An array of tables starts each record with a double-bracket header such as [[records]]. Every key = value line below that header belongs to the record until the next header. Each key becomes a column. The header row is the union of all keys across the records, in the order each key is first seen, so a field that appears only in the last record still gets its own column.

Values convert to text as follows: strings are unquoted and unescaped, numbers keep their digits with underscores removed, booleans become true or false, and dates and times are copied as written. An inline table or array has no flat equivalent, so its cell holds compact JSON.

How it works

A small recursive parser reads the file one character at a time and keeps track of the line number for error messages. Each [[name]] header opens a new record, and key = value lines fill it. Values are typed as strings, numbers, booleans, date-times, arrays or tables. Numbers keep their written text, minus underscores, so 3_000 becomes 3000 and 7.25 stays 7.25. The records are then merged into one header row and written out as CSV.

Common use cases

  • Turning a list of [[service]] entries from a deployment config into a spreadsheet that a reviewer can sort by owner or port.
  • Exporting a set of test fixtures written in TOML so a QA team can filter them by status in a spreadsheet.
  • Converting an array of inline tables produced by a build script into rows for a database import.

How to use this tool

  1. Paste the TOML text, or upload a .toml file that contains your [[records]] blocks.
  2. Review the preview. The header row should list every key you expected, and each record should be one row.
  3. If an error names a line, fix that line. If it names a key or record set, fix that in the source, then convert again.
  4. Download the records as CSV, or open them in the CSV editor to sort by a key or filter on a column such as active.

Example

Input TOML (three records)

[[records]]
id = 1
name = "Ada Lovelace"
active = true
score = 9.5
tags = ["math", "engines"]

[[records]]
id = 2
name = 'Grace Hopper'
active = false
joined = 1952-06-01
address = { city = "Arlington", zip = "22201" }

[[records]]
id = 3_000
name = "Alan \"Turing\""
score = 7.25

Output CSV

id,name,active,score,tags,joined,address
1,Ada Lovelace,true,9.5,"[""math"",""engines""]",,
2,Grace Hopper,false,,,1952-06-01,"{""city"":""Arlington"",""zip"":""22201""}"
3000,"Alan ""Turing""",,7.25,,,

Tips for best results

  • Keep one record set in each file. When the converter finds two, it lists their names so you can split the file.
  • Quote a key that contains a space, for example "first name" = "Ada". Bare keys may use letters, digits, underscores and hyphens only.
  • Dates are not reformatted. 1979-05-27 stays exactly as typed, which keeps the spreadsheet import predictable.

Common errors and how to fix them

Found 2 record sets.
The file has two different [[name]] arrays, or a [[name]] array and a top-level array. Split them into separate files, because each conversion produces one table.
Standard [table] headers are not supported.
A header like [server] opens a single table, not a list. Turn it into a [[name]] record, or move its keys into the record that uses them.
Dotted keys are not supported.
A key such as address.zip is rejected. Write it as an inline table, address = { zip = "22201" }, so the value becomes one JSON cell.
The key "x" appears twice in the same record.
TOML forbids duplicate keys inside one table. Remove the earlier line, or rename one of the keys if both values are needed.

Best practices

  • Use the same key names in every record. A typo like nmae in one record creates a second column that is mostly empty.
  • Put a comment line above each [[name]] block in the source file. Comments are ignored by the converter and help when you revisit the file.
  • Convert the file as written by your tool, not a hand-edited copy, so a rerun of the export produces the same column order.

What the parser supports

Basic strings with double quotes support the escapes \b, \t, \n, \f, \r, \", \\ and the four- or eight-digit unicode forms. Literal strings with single quotes take their contents as-is. Integers and floats accept underscores between digits, exponents and the special values inf and nan. Booleans, offset date-times, local dates and local times are accepted and copied as text.

Arrays may span several lines and may end with a trailing comma. Inline tables must stay on one line, which is how TOML itself defines them. Comments start with # and run to the end of the line.

Why some TOML is rejected instead of guessed

A full TOML document can describe nested tables, dotted keys and multi-line strings, and turning those into flat columns requires decisions that differ from one spreadsheet to the next. The converter takes the simpler path: anything it cannot map to a single record row produces an error that points to the line, key or record set at fault. That keeps the output honest about what was converted.

Frequently asked questions

Can it convert a regular TOML config file with tables and sections?

Not directly. Sections such as [database] are rejected. The converter is built for lists of records, so a config that is mostly named sections should be converted by hand or with a script that flattens it first.

Are the date values converted to a date format a spreadsheet understands?

They are left as text, exactly as written in the file. Most spreadsheets will recognize ISO dates such as 1952-06-01 on import, but the converter itself does not reformat them.

Why does a nested value look like JSON in the cell?

CSV has no way to hold a table inside a cell, so an inline table or array is stored as JSON. You can parse that text again in a spreadsheet formula or a script.

For more background on data formats and conversion workflows, read our format guides.