DeepDiff

8.6.2 · active · verified Sat Mar 28

DeepDiff is a Python library designed for deep comparison and search operations across various Python objects and data structures, including dictionaries, lists, strings, and custom objects. It recursively identifies all differences, providing detailed reports. DeepDiff also supports hashing objects based on their content (DeepHash) and creating/applying 'deltas' to reconstruct objects. The current version is 8.6.2, and it maintains an active release cadence with frequent updates.

Warnings

breaking A critical security vulnerability (CVE-2025-58367) was present in the Delta class, allowing class pollution leading to Denial of Service and Remote Code Execution via insecure Pickle deserialization.
Fix: Upgrade to DeepDiff version 8.6.1 or later.
breaking The default behavior of `threshold_to_diff_deeper` changed from 0 to 0.33. This means that if less than one-third of keys intersect between two dictionaries, DeepDiff will report the entire dictionary as a `new_value` instead of detailing individual key changes.
Fix: To restore the pre-8.0.0 behavior, set `threshold_to_diff_deeper=0` when initializing DeepDiff.
breaking Support for Python 3.7 was officially dropped.
Fix: Ensure your project runs on Python 3.8 or a newer supported version (currently Python 3.9+ is required).
gotcha The behavior of `use_enum_value` was changed. When `use_enum_value=True`, enum comparisons now use the enum's value directly, which can alter how enum-to-string or enum-to-other-value comparisons are reported.
Fix: Review your diffing logic involving Enums and explicitly set `use_enum_value=False` if you require the older comparison behavior, or adjust expectations based on the new `use_enum_value=True` default.
gotcha The `DeepHash` functionality was changed to raise an `Exception` if it encounters a value it cannot hash, instead of silently logging the issue.
Fix: Implement error handling around `DeepHash` calls or ensure that all objects passed to `DeepHash` are hashable by its internal logic.
gotcha The `ignore_type_subclasses` parameter had its behavior incorrectly reversed prior to version 7.0.0. It performed the opposite of its intended function.
Fix: If upgrading from versions older than 7.0.0 and using `ignore_type_subclasses`, you may need to invert its boolean value in your configurations.
deprecated The `verify_symmetry` parameter has been deprecated.
Fix: Use the `bidirectional` parameter instead.

Install

pip install deepdiff Standard install
pip install "deepdiff[optimize]" With optimization (e.g., orjson)
pip install "deepdiff[cli]" With command-line interface

Imports

DeepDiff
```
from deepdiff import DeepDiff
```
DeepSearch
```
from deepdiff import DeepSearch
```
DeepHash
```
from deepdiff import DeepHash
```
Delta
```
from deepdiff import Delta
```
grep
```
from deepdiff import grep
```
A convenient alias for DeepSearch functionality.

Quickstart

This quickstart demonstrates a basic comparison between two dictionaries using DeepDiff. It will output a dictionary detailing added items, removed items, and changed values between `t1` and `t2`.

from deepdiff import DeepDiff

t1 = {'name': 'Alice', 'age': 30, 'city': 'New York'}
t2 = {'name': 'Bob', 'age': 31, 'city': 'London', 'occupation': 'Engineer'}

diff = DeepDiff(t1, t2)
print(diff)

view raw JSON →