DeepDiff 9.2.0 documentation!

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_keys to 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, and Delta round-trips (#664)

  • Support for Python 3.15

  • Dropping support for Python 3.10, which reached end-of-life in October 2026

  • Fixed iterable_compare_func dropping 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 the int → float change like DeepDiff(2, 2.0) already does (#605) thanks to Sanjays2402

  • Fixed truncate_datetime crashing on non-truncatable types: it now applies only to datetime.datetime and datetime.time objects, so datetime.date, timedelta and np.datetime64 values are compared exactly instead of raising AttributeError thanks to SAY-5 and Sanjays2402

  • Fixed number_to_string producing an invalid string such as 1.0+-1.0j for complex numbers with a negative imaginary part, which crashed e.g. DeepHash(1-1j, significant_digits=3) (#551) thanks to koriyoshi2041 and Sanjays2402

  • Fixed Delta JSON round-trip crashing with TypeError when orjson is not installed, for list diffs that use iterable opcodes thanks to chuenchen309

  • Fixed _dict_from_slots dropping a parent-declared mangled __slots__ attribute for a subclass instance (#506) thanks to uttam12331

  • The deep command now exits with an actionable message (pip install "deepdiff[cli]") instead of a ModuleNotFoundError traceback when the cli extra is not installed (#594) thanks to uttam12331

  • Fixed 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

Indices and tables