CSV to TOML Converter
TOML is the configuration format behind many tools, and its array-of-tables syntax maps neatly onto a spreadsheet: one [[name]] header per row, followed by key and value lines. This CSV to TOML converter writes that structure for you, typing numbers and booleans as TOML values and quoting everything else as a properly escaped string.
A config or data loader usually expects its records under one array name, so set that name first (records by default), then copy the output into the file the loader reads.
A typical case: a ZIP column that holds 02108 and 10001 comes out as one quoted string and one bare integer, and that mismatch is what the notes below explain how to avoid.
Key features
- Writes one [[records]]-style table per CSV row, with the array name set in the options.
- Types each cell as a boolean, integer, or float when it is unambiguous, and as a string otherwise.
- Escapes quotes, backslashes, tabs, and line breaks in strings, and writes other control characters as Unicode escapes.
- Sanitises the array name so only letters, digits, underscore, and hyphen remain.
- Keeps header order, so each table lists its keys in the same order as the columns.
- Writes the array name you choose into every table header, so one edit of the option renames the whole file.
About the CSV to TOML array of tables format
Every CSV data row becomes one table in an array of tables. The array name is set in the TOML array name field and defaults to records, so the first row prints as [[records]] followed by its key-value lines. Rows are separated by one blank line, and the file ends with a single newline.
Keys come from the header row. Spaces become underscores, a leading digit gets a column_ prefix, and any character outside letters, digits, underscore, and hyphen is removed, so the keys are valid TOML bare keys. Duplicate headers receive a numeric suffix so each key is unique within its table.
Values follow four rules, applied in order. A cell reading true or false in any letter case becomes a lowercase TOML boolean. A whole number with no leading zero that fits in a signed 64-bit integer becomes an unquoted integer. A decimal with digits on both sides of the point, such as -2.25, becomes an unquoted float. Everything else, including empty cells, becomes a basic string in double quotes.
How it works
The converter parses the CSV with quoted-field support and normalises the header row into bare TOML keys.
For each row it types each value with a small set of anchored patterns. A whole number must match an integer shape with no leading zero, and it must fall within the signed 64-bit range; a decimal must have digits on both sides of the point. Booleans are matched without regard to case.
Each row is written as a [[array]] header followed by its key-value lines. The rows are joined with blank lines and a final newline is added.
Common use cases
- Generating a list of redirects, feature flags, or service endpoints from a spreadsheet into a TOML config file.
- Creating a static site data file where each entry in a CSV becomes one record the templates can loop over.
- Building a test fixture in TOML for a Rust or Python project that reads its sample data from a TOML file.
- Converting a product catalogue export into a TOML data file for a build step that reads TOML.
- Producing a small lookup table of regional settings to version alongside an application's config.
How to use this tool
- Paste your CSV or upload a .csv file. Put the field names on the first row.
- Enter the TOML array name, or leave it as records. Any character other than a letter, digit, underscore, or hyphen is replaced with an underscore.
- Click Convert and check the first and last tables in the preview for correct types.
- Copy the output or download it as a .toml file, then paste it into your config or data directory.
- Load the file in the application that reads it and confirm one value of each type is read as you expect.
Example
Input CSV
name,age,active,zip,score,comment
Ada,36,true,02108,9.5,"Says ""hi"""
Grace,85,FALSE,10001,-2.25,"two
lines"Output TOML
[[records]]
name = "Ada"
age = 36
active = true
zip = "02108"
score = 9.5
comment = "Says \"hi\""
[[records]]
name = "Grace"
age = 85
active = false
zip = 10001
score = -2.25
comment = "two\nlines"
Tips for best results
- Name the array for what each row represents, such as servers or plans, instead of the default records. The name appears on every table and is easy to read in a diff.
- Clean up number formats first. A cell reading 1,200 is a string in TOML because the comma is not a digit separator, so write it as 1200 if you want an integer.
- Values with a leading zero are always quoted, so if a column must be consistently a string, make sure every value in it keeps its leading zero or is treated as text downstream.
- Use short, plain headers, since they become the key names your application reads.
- Check the first and last table in the output, since they show the typed values for the first and last rows and are the fastest way to spot a type problem.
Common errors and how to fix them
- The converter reports that the CSV has no data rows.
- A header row alone would produce an empty TOML file, so the converter stops. Add at least one data row below the header.
- The array name in the output is not what I typed.
- Any character other than a letter, digit, underscore, or hyphen is replaced with an underscore, so my table! becomes my_table_. Use only those characters in the name.
- A column that should be numeric is written as a string.
- The value probably contains a thousands separator, a currency symbol, a leading plus sign, or a leading zero. Remove those in the sheet, because the converter only types plain digits and decimals.
- A key name is column_2nd_Place or column_3 instead of the header I wrote.
- The converter adds a column_ prefix to any header that starts with a digit. A header made only of symbols, or with no text at all, becomes column_ followed by its position. Rename the header to start with a letter if you want a clean key.
- A value containing a newline appears on one line in the output.
- That is expected. A multi-line cell is written as a basic string with \n escapes, which is valid TOML and keeps the record on one line of the file.
Best practices
- Decide on the array name and key names before generating the file, because renaming them later means editing every table.
- Preserve leading zeros when you export the CSV, for example by exporting code columns as text, because cell formatting inside the spreadsheet is not part of the CSV text the converter reads. Then check the converted types with a short test read in your application.
- Commit the generated TOML and the source CSV together so the data and its conversion can be reviewed in one change.
- Avoid storing secrets in the sheet, since the generated file is plain text that may be checked into version control.
The typing rules, in the order they are applied
The converter checks the boolean pattern first, so true and FALSE are written in lowercase. It then checks the integer pattern, which rejects a leading zero, a plus sign, a decimal point, or a thousands separator, and it confirms the value fits in 64 bits.
The float pattern requires a digit before and after the decimal point, so .5 and 5. are strings. Anything that fails all of these checks becomes a quoted string, which is the safe fallback for TOML.
- true, FALSE, and other case variants become lowercase booleans.
- 36 and -4 become integers; 02108 and +4 stay strings.
- 9.5 and -2.25 become floats; 1,200 and 1e5 stay strings.
Escaping strings for TOML
Basic strings in TOML use double quotes, so the converter escapes backslashes and double quotes. Tabs, line feeds, carriage returns, backspace, and form feed use their short escapes, and other control characters use the \uXXXX form.
This means a cell containing a quotation such as Says "hi" is written as Says \"hi\" inside the quotes, and the reader gets back the original text.
Array of tables versus one large table
An array of tables is the right shape when each row is a separate item of the same kind, such as a server, a plan, or a product. Each table can be read as one object by most TOML parsers.
If your data is a single set of settings rather than a list, a CSV is the wrong starting point. Write those settings directly in TOML, since a one-row CSV would produce a single table that is harder to read than a hand-written section.
Frequently asked questions
Why is my ZIP code written as a number in some rows and a string in others?
The converter types each cell on its own, by its content. A ZIP with no leading zero is a valid integer, while one with a leading zero is quoted. If the type must be consistent, edit those values in the generated file or have your application convert the field when it reads it.
Does the converter write TOML date types?
No. Date-like values are written as strings, so your application needs to parse them if it expects a datetime value.
Can I change the default records name after converting?
Yes, but the change must be made on every [[records]] header line. Setting the name before converting avoids that work.
For more background on data formats and conversion workflows, read our format guides.