JSON to TOML Converter Complete Guide 2026

Why Convert JSON to TOML?

JSON to TOML conversion is essential when you want to:

• Create human-readable configuration — TOML is easier to read and edit manually
• Add comments to config files — TOML supports inline comments with #
• Use with Rust Cargo — Cargo.toml is the standard for Rust projects
• Work with Python Poetry — pyproject.toml uses TOML format
• Configure Hugo or Zola — Popular static site generators use TOML
• Reduce file size — TOML is typically 20-30% smaller than JSON

How to Convert JSON to TOML

Method 1: Online JSON to TOML Converter (Fastest)

For quick one-off conversions:

1. Copy your JSON content
2. Paste into the converter input
3. Click "Convert" to generate TOML
4. Copy the result or download as .toml file

Method 2: Python

import json
import toml

# Read JSON file
with open('config.json', 'r') as f:
    json_data = json.load(f)

# Convert to TOML string
toml_string = toml.dumps(json_data)
print(toml_string)

# Save to file
with open('config.toml', 'w') as f:
    f.write(toml_string)

Method 3: Node.js

const fs = require('fs');
const toml = require('toml-j0.4');

// Read JSON file
const jsonData = JSON.parse(fs.readFileSync('config.json', 'utf8'));

// Convert to TOML
const tomlString = toml.stringify(jsonData);
console.log(tomlString);

// Save to file
fs.writeFileSync('config.toml', tomlString);

Method 4: Go

package main

import (
    "encoding/json"
    "os"
    "github.com/BurntSushi/toml"
)

func main() {
    // Read JSON
    var data map[string]interface{}
    jsonData, _ := os.ReadFile("config.json")
    json.Unmarshal(jsonData, &data)

    // Write TOML
    f, _ := os.Create("config.toml")
    encoder := toml.NewEncoder(f)
    encoder.Encode(data)
}

JSON to TOML Type Mapping

String Values

// JSON
{
  "title": "My Application",
  "description": "A sample config"
}

# TOML
title = "My Application"
description = "A sample config"

Numbers

// JSON
{
  "port": 8080,
  "pi": 3.14159,
  "negative": -42
}

# TOML
port = 8080
pi = 3.14159
negative = -42

Booleans

// JSON
{
  "enabled": true,
  "debug": false
}

# TOML
enabled = true
debug = false

Arrays

// JSON
{
  "tags": ["rust", "python", "go"],
  "ports": [80, 443, 8080]
}

# TOML
tags = ["rust", "python", "go"]
ports = [80, 443, 8080]

Nested Objects

// JSON
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "credentials": {
      "username": "admin",
      "password": "secret"
    }
  }
}

# TOML
[database]
host = "localhost"
port = 5432

[database.credentials]
username = "admin"
password = "secret"

Real-World Examples

Example 1: Package Configuration

// JSON (npm package.json style)
{
  "name": "my-rust-project",
  "version": "1.0.0",
  "author": "John Doe",
  "dependencies": {
    "serde": "1.0",
    "tokio": "1.0"
  }
}

# TOML (Cargo.toml)
name = "my-rust-project"
version = "1.0.0"
author = "John Doe"

[dependencies]
serde = "1.0"
tokio = "1.0"

Example 2: Application Settings

// JSON
{
  "app": {
    "name": "MyApp",
    "debug": true
  },
  "server": {
    "host": "0.0.0.0",
    "port": 3000
  },
  "features": ["auth", "logging", "cache"]
}

# TOML
[app]
name = "MyApp"
debug = true

[server]
host = "0.0.0.0"
port = 3000

features = ["auth", "logging", "cache"]

Example 3: Database Configuration

// JSON
{
  "production": {
    "adapter": "postgresql",
    "host": "db.example.com",
    "port": 5432,
    "database": "myapp_prod",
    "pool": 10
  },
  "development": {
    "adapter": "sqlite",
    "database": "dev.db"
  }
}

# TOML
[production]
adapter = "postgresql"
host = "db.example.com"
port = 5432
database = "myapp_prod"
pool = 10

[development]
adapter = "sqlite"
database = "dev.db"

Handling Special Cases

Dates and Times

// JSON
{
  "created_at": "2026-03-10T14:30:00Z",
  "date_only": "2026-03-10",
  "time_only": "14:30:00"
}

# TOML (with native datetime support)
created_at = 2026-03-10T14:30:00Z
date_only = 2026-03-10
time_only = 14:30:00

Arrays of Objects

// JSON
{
  "servers": [
    {"name": "web1", "port": 80},
    {"name": "web2", "port": 81}
  ]
}

# TOML (array of tables)
[[servers]]
name = "web1"
port = 80

[[servers]]
name = "web2"
port = 81

Multi-line Strings

// JSON
{
  "description": "Line 1\nLine 2\nLine 3"
}

# TOML (using literal strings)
description = """
Line 1
Line 2
Line 3"""

Popular Tools Using TOML

Rust — Cargo.toml

[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

Python — pyproject.toml (Poetry)

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample project"

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"

Hugo — config.toml

baseURL = "https://example.com"
languageCode = "en-us"
title = "My Hugo Site"

[params]
  description = "A tech blog"
  author = "John Doe"

Zola — config.toml

base_url = "https://example.com"
title = "My Zola Site"
compile_sass = true
build_search_index = true

Best Practices

1. Validate JSON first — Ensure input JSON is valid before conversion
2. Flatten deeply nested structures — TOML reads better with flatter hierarchies
3. Use tables for logical groups — Group related settings under [table] headers
4. Add comments in TOML — Explain complex configuration values
5. Keep arrays homogeneous — All elements should be the same type

Common Pitfalls

Null Values

TOML doesn't have a native null type. Options:

# Use empty string
value = ""

# Use empty array
items = []

# Omit the key entirely (recommended)
# Don't include: value = null

Mixed Type Arrays

// JSON (valid)
{ "mixed": [1, "two", true] }

# TOML (will cause issues - avoid)
mixed = [1, "two", true]

# Better: use tables
[[mixed]]
value = 1
type = "number"

[[mixed]]
value = "two"
type = "string"

Libraries for JSON to TOML

Python

• toml — Read/write TOML
• tomlkit — Preserve comments and formatting

Node.js

• toml-j0.4 — TOML 0.4 compatible
• @iarna/toml — Fast, supports TOML 1.0

Go

• github.com/BurntSushi/toml — Official, recommended
• github.com/pelletier/go-toml — Feature-rich

Rust

• toml — Official crate
• toml_edit — Preserves formatting

Frequently Asked Questions

Can all JSON be converted to TOML?

Most JSON can be converted, but there are edge cases: null values, mixed-type arrays, and extremely deep nesting may require manual adjustments.

Is TOML better than JSON for configs?

For human-edited configuration, yes. TOML is more readable, supports comments, and has a cleaner syntax. For machine-to-machine data exchange, JSON is still preferred.

What's the TOML version?

TOML 1.0.0 is the current stable version (released 2021). Most tools support it. Check the official TOML spec.

How do I add comments during conversion?

JSON doesn't support comments, so you'll need to add them manually after conversion in a text editor.

Related Resources

• TOML Formatter & Validator
• JSON Formatter & Validator
• TOML to JSON Complete Guide
• YAML to JSON Complete Guide