---
id: json-diff
version: "1.5.0"
license: unclear
license_treatment: permissive
maintenance: abandoned
---

# json-diff — Generates diff between two JSON files

License: permissive · Maintenance: abandoned · Downloads: 357.2K/mo

## What it is and what it does

json-diff is a command-line tool and Python library that compares two JSON files and outputs the structural differences in JSON format. It supports filtering the comparison by including or excluding specific keys, making it useful for detecting changes between JSON documents. The tool can be used both as a standalone script (with exit status indicating whether differences were found) and as an importable Python module.

The package has no runtime dependencies, making installation straightforward. However, it has been abandoned since August 2019; while it was ported to Python 3 in version 1.5.0, one test was left skipped, suggesting the port may not be complete. The codebase originated with Python 2.4 compatibility as a design constraint, which may affect its behavior on modern Python versions.

Use it for:

- Detect structural changes between two JSON configuration files in a deployment pipeline.
- Compare JSON API responses across different versions to identify breaking changes.
- Generate a diff report when JSON data is updated, for audit or version-control purposes.
- Exclude specific keys (like timestamps or IDs) when comparing JSON documents for meaningful content differences.
- Automate testing by comparing expected and actual JSON output from a program.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Compares two JSON files and generates a JSON output showing the differences, with options to include or exclude specific keys from the comparison.

No. The package is abandoned with no maintenance since 2019, incomplete Python 3 porting (one test skipped), and high install friction. For JSON comparison, consider actively maintained alternatives or use Python's built-in difflib with json.load() for simple cases. Install only if you have a specific legacy requirement and can accept the lack of support.

## Install

pip install json-diff
uv add json-diff
poetry add json-diff

## Installing json-diff

Before you install: Installation friction is high due to the source distribution format. The package is abandoned as of 2019-08-25 with no maintenance activity since; the last release ported to Python 3 but left one test skipped. Use only if you need this specific tool and can tolerate lack of ongoing support.

License in practice: Released under MIT/X11 license (permissive), so you can use, modify, and distribute it freely with minimal restrictions.

Quickstart:

pip install json-diff

import json_diff

result = json_diff.compare(json1, json2)

The package is abandoned; Python 3 support was added in 1.5.0 but one test remains skipped, indicating incomplete porting.

Verify before relying:

- Whether the skipped test in the Python 3 port indicates a functional limitation or just incomplete test coverage.
- Current compatibility with modern Python versions beyond the initial 3.x port in 2019.
- Whether the command-line tool works reliably given the abandoned maintenance status.

## Package facts

- License: not declared (permissive)
- Python support: unspecified
- Install friction: high
- Maintenance: abandoned
- Downloads: 357.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

json file comparison, json diff tool, compare json structures, json difference detector, json delta generator, json file diff, json structural comparison, json-tools, abandoned

[View on SkillFed](https://skillfed.io/packages/json-diff) · [View on PyPI](https://pypi.org/project/json-diff/)