---
id: recursive-diff
version: "2.1.0"
license: Apache
license_treatment: permissive
maintenance: active
---

# recursive-diff — Recursively compare two Python data structures

License: permissive · Maintenance: active · Downloads: 103.6K/mo

## What it is and what it does

recursive_diff is a utility for comparing two Python objects at any depth and reporting what differs between them. It's designed with scientific computing in mind—it has special handling for numpy arrays, pandas DataFrames, and xarray Datasets—so it can compare these structured data types meaningfully rather than just comparing object identity. The package is actively maintained, marked as Production/Stable, and requires Python 3.9 or later.

You would use it when you need to understand what changed between two versions of a complex nested data structure, whether that's a plain dict, a pandas table, or an xarray Dataset. It's particularly useful in testing, data validation, and debugging workflows where you want to see exactly which fields or rows differ rather than just getting a boolean 'equal or not' answer.

Use it for:

- Compare two pandas DataFrames to identify which rows or columns changed between versions.
- Validate that a data transformation pipeline produced the expected output by diffing before and after states.
- Debug scientific computations by recursively comparing xarray Datasets to spot where values diverged.
- Write tests that verify nested configuration dictionaries or API responses match expected structures.
- Track changes in nested Python objects during development or data processing workflows.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Recursively compares two Python data structures and reports their differences, with built-in support for numpy, pandas, and xarray objects.

Yes. The package is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem for anyone comparing complex nested data structures—especially in scientific and data engineering contexts. The Apache license is permissive. Install it if you regularly need to understand what differs between two versions of a pandas, xarray, or deeply nested Python object.

## Install

pip install recursive-diff
uv add recursive-diff
poetry add recursive-diff

## Installing recursive-diff

Before you install: Low friction installation with a pure-Python wheel. Actively maintained as of March 2026 with recent commits; marked Production/Stable. Depends on numpy, pandas, and xarray, which are widely available.

License in practice: Licensed under Apache (permissive), so you can use it freely in commercial and open-source projects without copyleft obligations.

Quickstart:

pip install recursive-diff

import recursive_diff

result = recursive_diff.recursive_diff({'a': 1}, {'a': 2})
print(result)

Requires Python 3.9 or later.

Verify before relying:

- Whether the package handles circular references or deeply nested structures gracefully.
- Performance characteristics when comparing very large pandas DataFrames or xarray Datasets.
- What format the diff output takes and whether it's suitable for programmatic consumption.

## Package facts

- License: Apache (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 103.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

recursive diff python, compare nested data structures, pandas dataframe diff, xarray comparison, deep object comparison, nested dict diff, data structure equality check, data-comparison, pandas-xarray, testing-validation

[View on SkillFed](https://skillfed.io/packages/recursive-diff) · [View on PyPI](https://pypi.org/project/recursive-diff/)