Python JSON Dump Human Readable

Working with JSON in Python is common. But raw JSON data is often a single line. This is hard to read.

You need a human-readable format. This helps with debugging and data inspection. The json.dump() method can create pretty output.

This article shows you how. We will use simple examples. You will learn to format JSON files cleanly.

What is json.dump()?

The json.dump() function writes JSON data to a file. It takes a Python object and a file object.

By default, it writes everything on one line. This is compact but not readable.

import json

data = {"name": "Alice", "age": 30, "city": "New York"}

with open("data.json", "w") as f:
    json.dump(data, f)

The output file data.json contains:

{"name": "Alice", "age": 30, "city": "New York"}

This is hard to scan. We need to add formatting.

Making JSON Human Readable with indent

The indent parameter adds whitespace. It makes the structure visible.

Set indent to a number, like 2 or 4. Each level of nesting gets that many spaces.

import json

data = {"name": "Alice", "age": 30, "city": "New York"}

with open("data_pretty.json", "w") as f:
    json.dump(data, f, indent=2)  # Indent with 2 spaces

Now the file looks like:

{
  "name": "Alice",
  "age": 30,
  "city": "New York"
}

This is much easier to read. Each key-value pair is on its own line.

Sorting Keys with sort_keys

When you have many keys, order matters. The sort_keys parameter sorts keys alphabetically.

Set it to True. This helps you find data quickly.

import json

data = {"z": 1, "a": 2, "m": 3}

with open("sorted.json", "w") as f:
    json.dump(data, f, indent=2, sort_keys=True)  # Sort keys alphabetically

Output:

{
  "a": 2,
  "m": 3,
  "z": 1
}

Without sort_keys, the order would be z, a, m. Sorting makes it predictable.

Handling Special Characters with ensure_ascii

By default, json.dump() escapes non-ASCII characters. This makes text like café look like caf\u00e9.

Set ensure_ascii=False to write the actual characters. This is more human-readable.

import json

data = {"name": "José", "city": "São Paulo"}

with open("unicode.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)  # Keep actual characters

Output:

{
  "name": "José",
  "city": "São Paulo"
}

This is much cleaner for international data.

Complete Example: All Parameters Together

You can combine all parameters. This gives you the best human-readable output.

import json

# Complex nested data
data = {
    "users": [
        {"name": "Alice", "age": 30, "email": "[email protected]"},
        {"name": "Bob", "age": 25, "email": "[email protected]"}
    ],
    "version": 2,
    "settings": {"debug": True, "theme": "dark"}
}

# Write with all formatting options
with open("output.json", "w", encoding="utf-8") as f:
    json.dump(
        data,
        f,
        indent=4,           # 4 spaces per indent level
        sort_keys=True,     # Sort keys alphabetically
        ensure_ascii=False  # Keep non-ASCII characters
    )

The output file is beautifully formatted:

{
    "settings": {
        "debug": true,
        "theme": "dark"
    },
    "users": [
        {
            "age": 30,
            "email": "[email protected]",
            "name": "Alice"
        },
        {
            "age": 25,
            "email": "[email protected]",
            "name": "Bob"
        }
    ],
    "version": 2
}

Notice the sorted keys and clear nesting. This is perfect for reading.

Using json.dumps() for Strings

Sometimes you need a string, not a file. Use json.dumps() instead.

It works the same way. Just pass the same parameters.

import json

data = {"name": "Alice", "age": 30}

pretty_string = json.dumps(data, indent=2, sort_keys=True)
print(pretty_string)

Output:

{
  "age": 30,
  "name": "Alice"
}

This is useful for logging or displaying data.

Common Pitfalls

Forgetting the indent parameter is the most common mistake. Without it, you get a single line.

Not opening the file in text mode with w can cause issues. Always use with open(file, 'w').

Ignoring encoding when using ensure_ascii=False. Always set encoding='utf-8' in the file open call.

Conclusion

Making JSON human-readable in Python is easy. Use json.dump() with the indent parameter.

Add sort_keys=True for consistent ordering. Use ensure_ascii=False for special characters.

These three parameters transform ugly JSON into a clean, readable format. Your debugging and data analysis will be much faster.

Start using them today in your Python projects. Your future self will thank you.