Python JSON Formatting Tools and Libraries

If you need to pretty-print JSON in Python today, start with the built-in json module. It is available everywhere, it handles both scripts and terminal use, and in current Python releases the command line interface is available as python -m json as well as the older python -m json.tool form.

The real decisions are not about syntax. They are about output quality and workflow: whether you want UTF-8 characters instead of escaped Unicode, whether you need strict JSON instead of JavaScript-style NaN values, whether your data is JSON Lines, and whether faster third-party serialization is worth giving up some flexibility.

What Should You Use?

The Default Choice: Python's json Module

The standard library remains the best starting point for most developers. It works for API responses, configuration files, test fixtures, and debug output, and it gives you more control over formatting than many faster alternatives.

Format with json.dumps()

These options matter most in real projects:

• indent: Use an integer such as 2 or 4 for normal pretty-printing, or pass a string such as "\t" if your team prefers tabs.
• ensure_ascii=False: Keeps UTF-8 characters readable instead of escaping everything above ASCII. This is usually the better choice for logs, fixtures, and user-facing output.
• sort_keys=True: Makes diffs easier to review and helps stabilize snapshots in tests.
• allow_nan=False: Raises an error for NaN, Infinity, and -Infinity so the output stays strict JSON.
• separators=(",", ":"): Useful when you want compact JSON instead of human-readable output.

Example: readable JSON with Unicode preserved

import json

payload = {
    "user": "Marina",
    "city": "Minsk",
    "message": "Привет",
    "roles": ["admin", "editor"]
}

pretty_json = json.dumps(
    payload,
    indent=2,
    ensure_ascii=False,
    sort_keys=True,
    allow_nan=False,
)

print(pretty_json)

That combination is a strong default for developer-facing output: it stays readable, produces predictable key order, and fails fast if the data is not valid JSON.

Write formatted files with json.dump()

Use json.dump() when you want to write directly to disk. For text files, explicitly opening with encoding="utf-8" avoids platform-default surprises.

import json

config = {
    "api_url": "https://example.com/v1",
    "timeout_seconds": 30,
    "features": {
        "pretty_logging": True,
        "strict_mode": True
    }
}

with open("config.json", "w", encoding="utf-8") as handle:
    json.dump(
        config,
        handle,
        indent=2,
        ensure_ascii=False,
        sort_keys=True,
    )

One easy mistake: JSON is not a framed format, so repeated calls to json.dump() on the same file do not create a valid stream of separate documents. If you need one object per line, use JSON Lines instead.

Command-Line Formatting with python -m json

For shell use, Python's built-in CLI is still the most practical formatter when you already have Python installed. In Python 3.14, the documentation exposes the command as python -m json; the older python -m json.tool entry point remains useful for compatibility and behaves the same way for most workflows.

Useful CLI patterns

• Pretty-print a file:

  python -m json payload.json

• Validate and sort keys:

  python -m json --sort-keys payload.json

• Preserve Unicode characters:

  cat payload.json | python -m json --no-ensure-ascii

• Handle JSON Lines or NDJSON correctly:

  python -m json --json-lines records.jsonl

• Switch formatting style:

  python -m json --indent 2 payload.json

  python -m json --tab payload.json

  python -m json --compact payload.json

The CLI also validates input. If the JSON is malformed, it exits with an error and points to the problem location, which makes it handy in shell scripts and CI checks.

Third-Party Libraries Worth Knowing

Most articles list a long catalog of JSON libraries. For formatting work, that usually adds noise. The main alternative worth evaluating is orjson, especially when formatting is part of a larger serialization path that needs to be fast.

When orjson is a better fit

orjson is designed for speed and produces UTF-8 bytes instead of Python strings. It supports pretty-printing with OPT_INDENT_2 and key sorting with OPT_SORT_KEYS, so it can work well in APIs and services where JSON serialization is on the hot path.

import orjson

payload = {
    "message": "Привет",
    "ok": True,
    "items": [1, 2, 3]
}

pretty_bytes = orjson.dumps(
    payload,
    option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS,
)

print(pretty_bytes.decode("utf-8"))

• Choose orjson when throughput matters and you are already comfortable handling bytes.
• Stay with the standard library when you need arbitrary indent widths, direct file writing with json.dump(), or the least surprising behavior for scripts and tooling.

Common Formatting Mistakes

• Treating JSON Lines like one big JSON document. A file with one object per line needs --json-lines or custom line-by-line handling.
• Forgetting that ensure_ascii=True is the default. If your output suddenly contains \\uXXXX escapes, set ensure_ascii=False.
• Assuming NaN and Infinity are always valid JSON. They are allowed by Python's default encoder, but not by strict JSON parsers.
• Assuming non-string dictionary keys round-trip cleanly. JSON object keys are strings, so loads(dumps(x)) can change the shape of your data.
• Pretty-printing huge payloads in memory during debugging. Indentation increases size, and converting a very large object to a single formatted string can be expensive.

Practical Recommendations

• For application code, use json.dumps(..., indent=2, ensure_ascii=False) unless you have a measured reason to do something else.
• For fixtures, config files, and snapshots, add sort_keys=True so diffs stay readable.
• For pipelines and quick validation, keep python -m json in your shell toolbox.
• For strict interoperability with external systems, add allow_nan=False and test with real payloads instead of assuming the defaults are portable.
• For sensitive one-off inspection, prefer a local or offline formatter over a random web app.

Conclusion

Python already gives you excellent JSON formatting tools. The standard json module is still the right default, the CLI covers day-to-day validation and terminal formatting, and orjson is worth considering when serialization speed matters more than formatting flexibility. If you understand Unicode, strict JSON, and JSON Lines, you will avoid most of the issues that make JSON formatting feel harder than it should.