Install & Compatibility
Where this runs
tested against v1.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.5s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
json_diff
✓ import json_diff.json_diff
✗ import 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'.
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)
json-diff --version
Errors
Common errors & fixes
json_diff: command not found
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.
fixInvoke 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'
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.
fixEnsure 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)
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.
fixFor 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.
Upgrade
Version history
1.5.0latest on PyPI · released Aug 25, 2019
Audit
Dependencies
No dependency data recorded yet.
Resources
No resource links recorded.