jsondiff

library2.2.1pypypi✓ verified 25d ago

jsondiff is a Python library designed to compare JSON and JSON-like structures, providing a detailed difference report. It is actively maintained, with its latest version being 2.2.1, and has a consistent release cadence with recent updates addressing bug fixes and new features.

serialization testing

pip install jsondiff

github ↗package ↗

INSTALL

IMPORT

SIG · JSONDIFF

jsondiff

serializationpythonv2.2.1

Install

1.7s avg

Import

138ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.2.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.140s · 20MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.136s · 21MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

diff

✓ from jsondiff import diff

The primary function for comparing JSON objects.

symbols

✓ from jsondiff import symbols

Used to access special symbols for diff output (e.g., 'insert', 'delete', 'update') when using explicit syntax.

This quickstart demonstrates how to use `jsondiff.diff` to compare two JSON objects. It shows both the default compact output and the more verbose 'explicit' syntax, which leverages `jsondiff.symbols` to clearly identify insertions, deletions, and updates within the JSON structures.

from jsondiff import diff, symbols json1 = { "name": "Alice", "age": 25, "city": "New York", "hobbies": ["reading", "hiking", "coding"] } json2 = { "name": "Bob", "age": 30, "city": "London", "occupation": "Engineer", "hobbies": ["reading", "running", "coding"] } # Basic diff (compact syntax by default) compact_diff = diff(json1, json2) print("Compact Diff:", compact_diff) # Explicit diff (more detailed output with symbols) explicit_diff = diff(json1, json2, syntax='explicit') print("\nExplicit Diff:", explicit_diff) # Accessing specific changes using symbols if symbols.insert in explicit_diff: print(" Inserted keys:", explicit_diff[symbols.insert]) if symbols.delete in explicit_diff: print(" Deleted keys:", explicit_diff[symbols.delete]) if symbols.update in explicit_diff: print(" Updated keys:", explicit_diff[symbols.update])

jsondiff --version

Debug

Known issues

breakingThe command-line interface (CLI) for `jsondiff` underwent breaking changes. The `jsondiff` command was deprecated in v1.2.0 in favor of `jdiff` and then entirely removed in v2.0.0. Users relying on the old CLI must switch to `jdiff` or implement programmatically.

fix

For CLI usage, install `jdiff` if available, or use the library programmatically. For example, `pip install jdiff` (note: `jdiff` is a separate package, ensure it matches your intended use) or integrate `from jsondiff import diff` into your Python scripts.

affects: <2.0.0

breakingSupport for Python versions prior to 3.8 was officially dropped in version 2.1.2. Users on Python 3.7 or older will encounter installation or runtime errors.

fix

Upgrade your Python environment to version 3.8 or newer. Alternatively, pin your `jsondiff` dependency to `<2.1.2`.

affects: >=2.1.2

gotchaThe `diff` function supports different output syntaxes: 'compact' (default), 'symmetric', and 'explicit'. The default 'compact' syntax may not always clearly distinguish between added/removed keys vs. changed values, which can be a source of confusion.

fix

Always consider explicitly setting `syntax='explicit'` for a more detailed and unambiguous diff report, especially for complex objects. This allows direct access to `symbols.insert`, `symbols.delete`, and `symbols.update`.

affects: All versions

gotchaVersion 2.2.0 introduced the ability to exclude specific paths from the diff calculation using the `exclude_paths` argument. Prior to this, achieving similar functionality would require manual post-processing of the diff result.

fix

For versions 2.2.0 and later, use the `exclude_paths` argument in the `diff` function (e.g., `diff(json1, json2, exclude_paths=['root.timestamp'])`). For older versions, filter the diff result manually.

affects: <2.2.0

gotchaAn issue where `Symbol.__eq__` was not robustly protected by an instance check was fixed in version 2.2.1. This could potentially lead to unexpected behavior or errors when comparing `jsondiff.symbols.xxx` objects with other non-symbol types.

fix

Upgrade to `jsondiff` version 2.2.1 or newer to ensure correct symbol comparison behavior.

affects: <2.2.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jsondiff'

The 'jsondiff' library has not been installed in your Python environment or the environment where your code is being executed.

fix

Install the library using pip: `pip install jsondiff`

AttributeError: 'str' object has no attribute 'items'

The `jsondiff.diff` function (or other functions expecting JSON-like structures) was called with a raw JSON string instead of a parsed Python dictionary or list.

fix

Parse the JSON string into a Python dictionary or list using `json.loads()` before passing it to `jsondiff.diff`. Example: `import json; from jsondiff import diff; obj1 = json.loads(json_string1); obj2 = json.loads(json_string2); result = diff(obj1, obj2)`

TypeError: keys must be a string

This error occurs when attempting to serialize the output of `jsondiff.diff` using Python's standard `json.dumps()` function. The `jsondiff` output can contain internal symbol objects or tuples as keys which are not directly JSON serializable by the standard library.

fix

Use `jsondiff.dumps()` instead of `json.dumps()` to serialize the diff object, as it is designed to handle `jsondiff`'s specific output format. Example: `from jsondiff import diff, dumps; obj1 = {'a': 1}; obj2 = {'a': 2}; d = diff(obj1, obj2); json_output = dumps(d)`

Upgrade

Version history

2.2.1latest on PyPI · released Aug 29, 2024

Audit

Dependencies

pythonrequiredRequires Python 3.8 or newer.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/xlwings/jsondiff ↗

packagehttps://pypi.org/project/jsondiff/ ↗