How to convert JSON to TOML
JSON and TOML both hold objects, lists, text, numbers and true or false. To convert json to toml, the tool checks your JSON, then writes the same data using TOML's tables: a heading in square brackets for each nested object, with plain key = value lines under it.
The built-in sample is a pyproject.toml written as one line of JSON. Converted with the default options, it gives:
[project]
name = "demo-app"
version = "0.4.1"
description = "A small command line tool"
requires-python = ">=3.10"
dependencies = ["httpx>=0.27", "pydantic>=2.6"]
[[project.authors]]
name = "Ada Lovelace"
email = "ada@example.com"
[[project.authors]]
name = "Grace Hopper"
[tool.ruff]
line-length = 100
target-version = "py310"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"The status line reports 17 keys, 5 tables and 21 lines. The sample also had a license set to null. It is missing from the output on purpose, and the next section explains why.
What TOML cannot store, and how the tool tells you
TOML has no null. A JSON value of null has no TOML equivalent, so a converter has to drop it, replace it, or refuse. Many converters drop it without saying so, and you only find out when the program that reads the config misbehaves. Here every such value is listed under Not stored in TOML, with its JSON path. Take this input:
{"name":"app","license":null,"tags":["a",null,"b"],"retries":3.0,"id":12345678901234567890}name = "app"
tags = ["a", "b"]
retries = 3.0
id = 12345678901234567890.0The list names $.license and $.tags[1] as dropped. Note that dropping the null inside tags moves the second item, which is why the path is shown. Two other details are visible in the output. retries stays 3.0, so a reader sees a float and not an integer. And id is too large for the 64-bit integers TOML allows, so it is written as a float with a note.
Set Null values to Write empty text to keep the key as an empty string, or to Stop with an error when a null should never be there. The error lists every path so you can fix the source.
Tables, inline tables and arrays of tables
TOML gives the same data three shapes. A nested object becomes a table with its own heading. A small object can sit on one line as an inline table, written { a = 1, b = 2 }. A list of objects becomes an array of tables, with the heading repeated in double square brackets for each item. A list of two objects looks like this:
[[items]]
id = 1
[[items]]
id = 2A list that mixes objects with numbers or text cannot use that form, so it is written as an array holding inline tables. TOML also needs plain values before the sections inside any table, so within one object the plain values are written first, then its sub-tables. If your JSON mixes them in another order, the TOML keeps each value but groups them this way.
A TOML file must be a table at the top. If your JSON is an array or a single value, the tool puts it under a key you choose, which is items by default, and says so in the notes.
Convert JSON to TOML for pyproject, Cargo, wrangler and MCP files
The sample buttons load small configs of each kind so you can see the pattern. For a Cargo manifest, turn on Inline small objects and a dependency such as serde with a few simple keys fits on one line:
[dependencies]
serde = { version = "1", features = ["derive"] }
clap = "4.5"
regex = "1.10"That is the usual way to write dependencies by hand. Keep the option off for the profile.release table, or edit the result, because the inline form turns it into one line under a profile heading.
Wrangler reads wrangler.toml as well as wrangler.json and wrangler.jsonc, and Cloudflare recommends the JSONC form for new projects. If you have a JSONC file with comments, turn on Allow comments and trailing commas and they are removed before conversion. Use the pasted result as a starting point, since comments cannot come across from JSON.
MCP server settings are often stored as JSON under a key named mcpServers, while OpenAI's Codex CLI reads a TOML table named mcp_servers in its config.toml. The conversion handles the structure. You change the key name yourself. With a key of mcp_servers the MCP sample becomes:
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
[mcp_servers.filesystem.env]
LOG_LEVEL = "info"
[mcp_servers.docs]
url = "https://example.com/mcp"Such a config can hold tokens. The conversion runs in your browser and nothing is sent anywhere, but check the file before you share it.
Options explained
- Null values: drop them and list the paths, write them as empty text, or stop with an error.
- Sort keys: puts the keys of every table in alphabetical order. Off keeps the order of your JSON.
- Inline small objects: writes an object with up to three simple keys on one line instead of giving it a section.
- Multi-line text blocks: text containing line breaks is written between triple quotes. Off writes one line with \n escapes.
- Date strings: keep 2026-10-30 as text, or write it as a TOML date. Only text in the exact date, time or date-time form is converted, and impossible dates such as February 30 stay text.
- Allow comments and trailing commas: reads JSONC, for example a wrangler.jsonc, by removing // comments, /* */ comments and a comma before } or ].
- Key for a top-level array: the name used when the JSON is not an object.
JSON to TOML in Python
Python 3.11 added tomllib, which reads TOML but cannot write it. To write TOML you need a package such as tomli-w:
import json
import tomli_w
with open('config.json') as f:
data = json.load(f)
with open('config.toml', 'wb') as f:
tomli_w.dump(data, f)TOML has no null, so remove None values from the data first. This page does that for you and lists what it removed. To go back, use TOML to JSON. If your config is YAML instead, JSON to YAML and YAML to JSON cover that format. When the JSON arrives as an escaped string inside another file, JSON Unescape restores it, and JSONL Viewer helps with files that hold one JSON object per line.
Limits
- JSON has no comments, so the TOML you get has none. Add them by hand afterwards.
- Null values cannot be stored. They are dropped, replaced or reported, as you choose, and always listed.
- Whole numbers outside the 64-bit range are written as floats and may be rounded by the program that reads the TOML. A number too large even for a float, such as 1e400, is written as given and read back as inf.
- Text containing an unpaired surrogate, which is not valid Unicode, has that character replaced with U+FFFD.
- If the same key appears twice in one JSON object, the last value wins, as in JSON parsers.
- The tool checks that the TOML it writes follows the format, not that your project accepts the values. It cannot know which keys pyproject.toml or Cargo.toml expect.
Your JSON is converted in your browser. It is not uploaded or stored. See the Privacy Policy for details.