DeepDiff 9.2.1 documentation!¶
DeepDiff is part of Qluster
Qluster helps teams resolve bad data in recurring file submissions, such as insurance bordereaux, before release: versioned rules check every row, AI agents propose fixes, and people approve what goes out. See DeepDiff and Qluster for when it fits.
Modules¶
The DeepDiff library includes the following modules:
DeepDiff For Deep Difference of 2 objects. DeepDiff
It returns the deep difference of python objects. It can also be used to take the distance between objects. Deep Distance
DeepSearch Search for objects within other objects. DeepSearch
DeepHash Hash any object based on their content even if they are not “hashable” in Python’s eyes. DeepHash
Delta Delta of objects that can be applied to other objects. Imagine git commits but for structured data. Delta
Extract For extracting a path from an object Extract
Commandline Most of the above functionality is also available via the commandline module Command Line
What Is New¶
DeepDiff 9-2-0¶
Added
iterable_match_keysto match list items by key per path, e.g.{"root['orders']": "order_id", "root['orders'][*]['lines']": ("sku", "warehouse")}. Inserted, removed and reordered records are reported per record at real list indexes, andDeltaround-trips (#664)Support for Python 3.15
Dropping support for Python 3.10, which reached end-of-life in October 2026
Fixed
iterable_compare_funcdropping an added item whose content equals an item that was already matched, e.g.[{"id": 1}]vs[{"id": 1}, {"id": 1}]returned{}(#665)Fixed missing type changes between equal-comparing items inside ordered iterables, e.g.
DeepDiff([2], [2.0])now reports theint→floatchange likeDeepDiff(2, 2.0)already does (#605) thanks to Sanjays2402Fixed
truncate_datetimecrashing on non-truncatable types: it now applies only todatetime.datetimeanddatetime.timeobjects, sodatetime.date,timedeltaandnp.datetime64values are compared exactly instead of raisingAttributeErrorthanks to SAY-5 and Sanjays2402Fixed
number_to_stringproducing an invalid string such as1.0+-1.0jfor complex numbers with a negative imaginary part, which crashed e.g.DeepHash(1-1j, significant_digits=3)(#551) thanks to koriyoshi2041 and Sanjays2402Fixed Delta JSON round-trip crashing with
TypeErrorwhen orjson is not installed, for list diffs that use iterable opcodes thanks to chuenchen309Fixed
_dict_from_slotsdropping a parent-declared mangled__slots__attribute for a subclass instance (#506) thanks to uttam12331The
deepcommand now exits with an actionable message (pip install "deepdiff[cli]") instead of aModuleNotFoundErrortraceback when thecliextra is not installed (#594) thanks to uttam12331Fixed typos in docstrings and comments thanks to Labib-Bin-Salam
Updated dependencies, and switched release tooling from bump2version to bump-my-version
Tutorials¶
Tutorials can be found on Zepworks blog
Installation¶
Install from PyPi:
pip install deepdiff
If you want to use DeepDiff from commandline:
pip install "deepdiff[cli]"
If you want to improve the performance of DeepDiff with certain processes such as json serialization:
pip install "deepdiff[optimize]"
Read about DeepDiff optimizations at Optimizations
Importing¶
>>> from deepdiff import DeepDiff # For Deep Difference of 2 objects
>>> from deepdiff import grep, DeepSearch # For finding if item exists in an object
>>> from deepdiff import DeepHash # For hashing objects based on their contents
>>> from deepdiff import Delta # For creating delta of objects that can be applied later to other objects.
>>> from deepdiff import extract # For extracting a path from an object
Note
if you want to use DeepDiff via commandline, make sure to run:
pip install "deepdiff[cli]"
Then you can access the commands via:
DeepDiff
$ deep diff --help
Delta
$ deep patch --help
grep
$ deep grep --help
extract
$ deep extract --help
Supported data types¶
int, string, unicode, dictionary, list, tuple, set, frozenset, OrderedDict, NamedTuple, Numpy, custom objects and more!
References¶
- DeepDiff
DeepDiff- Basics
- Customized Diff
- Deep Distance
- Exclude Paths
- Include Paths
- Ignore Order
- Ignore Types Or Values
- Exclude Types
- Ignore String Type Changes
- Ignore Numeric Type Changes
- Ignore Type In Groups
- Ignore Type Subclasses
- Ignore UUID Types
- Ignore String Case
- Ignore Nan Inequality
- Ignore Private Variables
- Exclude Obj Callback
- Exclude Obj Callback Strict
- Include Obj Callback
- Include Obj Callback Strict
- Truncate Datetime
- Use Enum Value
- Iterable Match Keys
- Numbers
- Optimizations
- Other Parameters
- Serialization
- Stats and Logging
- Troubleshoot
- View
- DeepSearch
- DeepHash
- Delta
- Diff to load in Delta
- Delta Path parameter
- Delta File parameter
- Flat Dict List
- Flat Rows List
- Delta Deserializer
- Delta Serializer
- Delta Serialize To Flat Dictionaries
- Delta Dump Safety
- Delta Mutate parameter
- Delta and Numpy
- Delta Raise Errors parameter
- Delta Safe To Import parameter
- Delta Verify Symmetry parameter
- Delta Force
- Always Include Values
- Extract
- Colored View
- Command Line
- Changelog
- Authors
- F.A.Q
- Q: DeepDiff report is not precise when ignore_order=True
- Q: The report of changes in a nested dictionary is too granular
- Q: TypeError: Object of type type is not JSON serializable
- Q: How do I parse DeepDiff result paths?
- Q: Why my datetimes are reported in UTC?
- Q: Is there a tool for fixing recurring data files, not just diffing them?
- Support
- DeepDiff and Qluster