quick-json-diff

A fast JSON diff tool built entirely with the Python standard library — no third-party dependencies required.

Recursively compare two JSON objects and produce a structured list of all differences (added, removed, or modified values), each annotated with a clear dot-notation path.

Features

• Zero dependencies — powered by Python standard library only
• Recursive comparison — drill into nested dicts and lists automatically
• Clear path output — each difference includes a dot-notation / bracket-notation path (e.g., variables[3].spec.sort)
• Three diff kinds — added, removed, modified for every change
• CLI + Python API — use it from the command line or as a library
• Safe & predictable — pure Python dataclass output, easy to serialise

Installation

python -m pip install quick-json-diff

Usage

CLI

json-diff <left_json_file> <right_json_file>

Example:

json-diff test_left.json test_right.json

Output:

[
    {
        "path": "variables[3].spec.sort",
        "kind": "modified",
        "left": "alphabeticalAsc123",
        "right": "alphabeticalAsc"
    }
]

Python API

import json
from quick_json_diff import JsonDiffer

left = JsonDiffer.read_json("test_left.json")
right = JsonDiffer.read_json("test_right.json")
differ = JsonDiffer(left, right)
result = differ.diff()

print(json.dumps(result, ensure_ascii=False, indent=2))

You can also work with raw Python objects directly:

from quick_json_diff import JsonDiffer

left = {"a": 1, "b": [1, 2, 3]}
right = {"a": 2, "b": [1, 2, 3, 4], "c": "new"}
differ = JsonDiffer(left, right)
result = differ.diff()

for item in result:
    print(f"{item['kind']}: {item['path']}")
    if item['left'] is not None:
        print(f"  left:  {item['left']}")
    if item['right'] is not None:
        print(f"  right: {item['right']}")

Output:

modified: a
  left:  1
  right: 2
added: c
  right: new
added: b[3]
  right: 4

Output Format

differ.diff() returns a list[dict]. Each dict has the following keys:

The same shape is available as the DiffResult dataclass:

from quick_json_diff import DiffResult

result: DiffResult  # .path, .kind, .left, .right

Contributing

Contributions are welcome! Here's how you can help:

1. Report issues — open a GitHub Issue for bugs or feature requests
2. Submit pull requests — fork the repo, make changes, and open a PR
3. Development setup:

   git clone https://github.com/rainuxhe/fastjsondiff.git
   cd quick-json-diff
   pip install -e ".[dev]"
   python -m build
   

Before submitting, please ensure the existing tests pass and add tests for new functionality.

License

MIT © 2026 Rainux He