JSON Diff (mcepl/json_diff)

1.5.0 · maintenance · verified Thu Apr 16

The `json-diff` library (maintained by mcepl) provides a command-line tool to compare two JSON files and output their structural differences. While it was ported to Python 3 in its 1.5.0 release, its development has been inactive since 2019. It aims to identify additions, deletions, and modifications between JSON structures, generating a new JSON file or console output with the result. This library is considered to be in maintenance mode due to its age and lack of recent updates.

Common errors

```
json_diff: command not found
```
cause Users often expect `json-diff` to install an executable command directly named `json_diff` (or `json-diff`) in their PATH, but this library's primary entry point for command-line execution is through the Python module system.

fix Invoke the tool using `python -m json_diff.json_diff <file1.json> <file2.json>` instead of just `json_diff`.
```
ModuleNotFoundError: No module named 'json_diff.json_diff'
```
cause This error occurs if the library was not installed correctly, or if you are trying to import `json_diff.json_diff` as a module directly without it being properly packaged or if you are using an incorrect path.

fix Ensure the library is installed with `pip install json-diff`. If trying to use programmatically, re-evaluate if this library is the right fit, as its primary mode is CLI via `python -m json_diff.json_diff`.
```
Incorrect or incomplete diff output for complex JSON structures (e.g., unordered arrays, floating-point differences)
```
cause The `json-diff` library, being older and focused on basic structural diff, may not handle advanced JSON comparison nuances such as semantic differences in unordered arrays, tolerance for floating-point numbers, or ignoring specific dynamic fields like timestamps.

fix For complex or modern JSON comparison needs, consider using more sophisticated and actively maintained libraries like `jsondiff` or `deepdiff` that offer features like array element matching, numeric tolerance, and configurable exclusions.

Warnings

deprecated The `json-diff` library has not seen active development since its 1.5.0 release in August 2019, and its original goal was Python 2.4 compatibility. While it has Python 3 support, it may not be actively maintained for modern Python environments or contemporary JSON comparison needs.
Fix: Consider using more actively maintained alternatives like `jsondiff` (xlwings/jsondiff), `deepdiff`, or `json_delta` for better support, features, and compatibility with recent Python versions and complex JSON structures.
gotcha The library primarily operates as a command-line tool via `python -m json_diff.json_diff`. There isn't a clearly documented programmatic API for direct function calls within Python scripts, which might frustrate users expecting a typical library interface.
Fix: Always invoke the tool using `subprocess.run(['python', '-m', 'json_diff.json_diff', ...])` or directly from the command line, as shown in the quickstart. Do not expect to `from json_diff import diff` directly.

Install

pip install json-diff Install latest version

Imports

json_diff
wrong:
```
import json_diff
```
correct:
```
import json_diff.json_diff
```
The primary interaction is via the command-line entry point 'json_diff.json_diff' within the installed 'json_diff' package, rather than a top-level module named 'json_diff'.

Quickstart

This quickstart demonstrates how to use `json-diff` via its command-line interface, which is its primary mode of operation. It compares two temporary JSON files and outputs the differences to a third file.

import os
import json
import subprocess

# Create dummy JSON files for demonstration
json1_data = {"name": "Alice", "age": 30, "city": "New York"}
json2_data = {"name": "Alice", "age": 31, "occupation": "Engineer"}

file1 = "file1.json"
file2 = "file2.json"
output_file = "diff_output.json"

with open(file1, "w") as f:
    json.dump(json1_data, f, indent=2)
with open(file2, "w") as f:
    json.dump(json2_data, f, indent=2)

# Run json-diff as a command-line tool
try:
    # Using python -m to invoke the module as a script
    command = ["python", "-m", "json_diff.json_diff", file1, file2, "-o", output_file]
    result = subprocess.run(command, capture_output=True, text=True, check=True)

    print("json-diff output:")
    print(result.stdout)
    if result.stderr:
        print("json-diff errors:")
        print(result.stderr)

    with open(output_file, 'r') as f:
        diff_result = json.load(f)
        print(f"\nDifferences written to {output_file}:")
        print(json.dumps(diff_result, indent=2))

except subprocess.CalledProcessError as e:
    print(f"Error running json-diff: {e}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
except FileNotFoundError:
    print("Error: 'python' command not found. Ensure Python is in your PATH.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    # Clean up dummy files
    for f in [file1, file2, output_file]:
        if os.path.exists(f):
            os.remove(f)

view raw JSON →