{"id":14649,"library":"json-diff","title":"JSON Diff (mcepl/json_diff)","description":"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.","status":"maintenance","version":"1.5.0","language":"en","source_language":"en","source_url":"https://gitlab.com/mcepl/json_diff","tags":["json","diff","comparison","cli","command-line","utility"],"install":[{"cmd":"pip install json-diff","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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'.","wrong":"import json_diff","symbol":"json_diff","correct":"import json_diff.json_diff"}],"quickstart":{"code":"import os\nimport json\nimport subprocess\n\n# Create dummy JSON files for demonstration\njson1_data = {\"name\": \"Alice\", \"age\": 30, \"city\": \"New York\"}\njson2_data = {\"name\": \"Alice\", \"age\": 31, \"occupation\": \"Engineer\"}\n\nfile1 = \"file1.json\"\nfile2 = \"file2.json\"\noutput_file = \"diff_output.json\"\n\nwith open(file1, \"w\") as f:\n    json.dump(json1_data, f, indent=2)\nwith open(file2, \"w\") as f:\n    json.dump(json2_data, f, indent=2)\n\n# Run json-diff as a command-line tool\ntry:\n    # Using python -m to invoke the module as a script\n    command = [\"python\", \"-m\", \"json_diff.json_diff\", file1, file2, \"-o\", output_file]\n    result = subprocess.run(command, capture_output=True, text=True, check=True)\n\n    print(\"json-diff output:\")\n    print(result.stdout)\n    if result.stderr:\n        print(\"json-diff errors:\")\n        print(result.stderr)\n\n    with open(output_file, 'r') as f:\n        diff_result = json.load(f)\n        print(f\"\\nDifferences written to {output_file}:\")\n        print(json.dumps(diff_result, indent=2))\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running json-diff: {e}\")\n    print(f\"Stdout: {e.stdout}\")\n    print(f\"Stderr: {e.stderr}\")\nexcept FileNotFoundError:\n    print(\"Error: 'python' command not found. Ensure Python is in your PATH.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up dummy files\n    for f in [file1, file2, output_file]:\n        if os.path.exists(f):\n            os.remove(f)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"<=1.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Invoke the tool using `python -m json_diff.json_diff <file1.json> <file2.json>` instead of just `json_diff`.","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.","error":"json_diff: command not found"},{"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`.","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.","error":"ModuleNotFoundError: No module named 'json_diff.json_diff'"},{"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.","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.","error":"Incorrect or incomplete diff output for complex JSON structures (e.g., unordered arrays, floating-point differences)"}],"ecosystem":"pypi"}