Recursive Diff

2.1.0 · active · verified Fri Apr 17

recursive-diff is a Python library that provides a function to recursively compare two Python data structures (dictionaries, lists, and basic types) and return a detailed diff. It is currently at version 2.1.0 and is actively maintained, with releases addressing bug fixes and minor enhancements.

Common errors

```
AttributeError: module 'recursive_diff' has no attribute 'diff_objects'
```
cause You are attempting to call the `diff_objects` function, which was removed in `recursive-diff` version 2.0.0.

fix Update your code to use the main `recursive_diff` function directly. Ensure it is imported as `from recursive_diff import recursive_diff` and called like `recursive_diff(obj1, obj2)`.
```
ImportError: cannot import name 'diff_objects' from 'recursive_diff' (path/to/recursive_diff/__init__.py)
```
cause You are trying to import `diff_objects` (or `diff_strings`), which is no longer exposed directly from the `recursive_diff` package since version 2.0.0.

fix Change your import statement to `from recursive_diff import recursive_diff`. The main function now handles all types of comparisons.
```
TypeError: 'set' objects are not subscriptable
```
cause Attempting to create a diff on a data structure containing sets directly when the library's pathing expects list-like or dict-like access. While the library handles basic elements, complex scenarios with sets might require conversion if specific element-wise diffing is desired.

fix Convert sets to lists before passing them to `recursive_diff` if order doesn't matter and you want to see individual element additions/removals. Example: `obj1_list = list(obj1_set)`.

Warnings

breaking The API for `diff_objects` and `diff_strings` was removed in version 2.0.0. Attempting to use these functions will result in an AttributeError or ImportError.
Fix: Migrate your code to use the main `recursive_diff` function directly. It now handles all data types that were previously covered by the specialized functions. Example: `from recursive_diff import recursive_diff; diff = recursive_diff(obj1, obj2)`.
gotcha The output of `recursive_diff` is a list of dictionaries, each describing a specific change (add, remove, change) with its path. It is not a traditional string-based diff or a simple boolean.
Fix: Familiarize yourself with the structure of the returned diff operations as documented in the library's README. You will need to iterate through this list to understand and process the differences.

Install

pip install recursive-diff Install latest version

Imports

recursive_diff
wrong:
```
from recursive_diff import diff_objects
```
correct:
```
from recursive_diff import recursive_diff
```
As of v2.0.0, the `diff_objects` and `diff_strings` functions were removed. Use `recursive_diff` directly for all data structure comparisons.

Quickstart

This quickstart demonstrates how to compare two complex Python dictionaries using `recursive_diff` and interpret the resulting list of operation dictionaries.

from recursive_diff import recursive_diff

obj1 = {
    "name": "Alice",
    "details": {"age": 30, "city": "New York", "preferences": {"color": "blue"}},
    "items": ["apple", "banana"],
    "tags": {"active": True}
}
obj2 = {
    "name": "Bob",
    "details": {"age": 31, "city": "London", "preferences": {"color": "red"}},
    "items": ["apple", "cherry"],
    "tags": {"active": True, "premium": True}
}

diff = recursive_diff(obj1, obj2)

# The diff is a list of operation dictionaries
# Example output structure:
# [
#   {'op': 'change', 'path': ['name'], 'old': 'Alice', 'new': 'Bob'},
#   {'op': 'change', 'path': ['details', 'age'], 'old': 30, 'new': 31},
#   {'op': 'change', 'path': ['details', 'city'], 'old': 'New York', 'new': 'London'},
#   {'op': 'change', 'path': ['details', 'preferences', 'color'], 'old': 'blue', 'new': 'red'},
#   {'op': 'remove', 'path': ['items', 1], 'old': 'banana'},
#   {'op': 'add', 'path': ['items', 1], 'new': 'cherry'},
#   {'op': 'add', 'path': ['tags', 'premium'], 'new': True}
# ]
print(diff)

view raw JSON →