Nested-Diff.py

Recursive diff and patch for nested structures.

PyPi Tests Coverage Supported Python versions License

Main features

  • Machine readable diff structure.
  • Human friendly diff visualization, collapsible html diffs.
  • All ops (added/removed/changed/unchanged) are optional and may be disabled.
  • Any data types support may be added by external handlers.

See Live Demo!

Install

pip install nested_diff

For extra formats support (YAML, TOML) in cli tools, use

pip install nested_diff[cli]

Command line tools

$ cat a.json b.json
[0, [1],    3]
[0, [1, 2], 3]

$ nested_diff a.json b.json
  [1]
+   [1]
+     2

nested_diff a.json b.json --ofmt json > patch.json
nested_patch a.json patch.json

Library usage

>>> from nested_diff import diff, patch
>>> from nested_diff.formatters import TextFormatter
>>>
>>> a = {'one': 1, 'two': 2, 'three': 3}
>>> b = {'one': 1, 'two': 42}
>>>
>>>
>>> full_diff = diff(a, b)
>>> full_diff
{'D': {'three': {'R': 3}, 'two': {'N': 42, 'O': 2}, 'one': {'U': 1}}}
>>>
>>> short_diff = diff(a, b, O=False, U=False)  # omit old and unchanged items
>>> short_diff
{'D': {'three': {'R': 3}, 'two': {'N': 42}}}
>>>
>>>
>>> a = patch(a, short_diff)
>>> assert a == b
>>>
>>>
>>> human_readable = TextFormatter().format(full_diff)
>>> print(human_readable)
  {'one'}
    1
- {'three'}
-   3
  {'two'}
-   2
+   42
<BLANKLINE>
>>>

HTML and ANSI colored terminal formatters also available out of the box.
See Live Demo, HOWTO and nested_diff.formatters.

Diff structure

Diff is a dict and may contain status keys:

  • A stands for 'added', it's value - added item.
  • D means 'different' and contains subdiff.
  • N is a new value for changed item.
  • O is a changed item's old value.
  • R key used for removed item.
  • U represent unchanged item.

and auxiliary keys:

  • C comment; optional, value - arbitrary string.
  • E extension ID (optional).
  • I index for sequence item, used only when prior item was omitted.

Diff metadata alternates with actual data; simple types specified as is, dicts, lists and tuples contain subdiffs for their items with native for such types addressing: indexes for lists and tuples, keys for dictionaries. Any status key, except D may be omitted during diff computation. E key is used with D when entity unable to contain diff by itself (set, frozenset for example); D contain a list of subdiffs in this case.

Annotated example

a:  {"one": [5,7]}
b:  {"one": [5], "two": 2}
opts: U=False  # omit unchanged items

diff:
{"D": {"one": {"D": [{"I": 1, "R": 7}]}, "two": {"A": 2}}}
| |   |  |    | |   || |   |   |   |       |    | |   |
| |   |  |    | |   || |   |   |   |       |    | |   +- with value 2
| |   |  |    | |   || |   |   |   |       |    | +- key 'two' was added
| |   |  |    | |   || |   |   |   |       |    +- subdiff for it
| |   |  |    | |   || |   |   |   |       +- another key from top-level
| |   |  |    | |   || |   |   |   +- what it was (item's value: 7)
| |   |  |    | |   || |   |   +- what happened to item (removed)
| |   |  |    | |   || |   +- list item's actual index
| |   |  |    | |   || +- prior item was omitted
| |   |  |    | |   |+- subdiff for list item
| |   |  |    | |   +- it's value - list
| |   |  |    | +- it is deeply changed
| |   |  |    +- subdiff for key 'one'
| |   |  +- it has key 'one'
| |   +- top-level thing is a dict
| +- changes somewhere deeply inside
+- diff is always a dict

License

Licensed under the terms of the Apache License, Version 2.0.

See Also

HOWTO

deepdiff, jsondiff, jsonpatch, json-delta

Project links

Data verified by PyPI on Aug 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mixas from gravatar.com mixas

Credits

Author: Michael Samoglyadov

GitHub Statistics

Data verified by PyPI on Aug 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License

Requires

Python >=3.7

Provides Extra

cli lint test

Tags

diff nested-diff recursive-diff nested-data data-structures

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nested_diff-1.11.0.tar.gz (23.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nested_diff-1.11.0-py3-none-any.whl (27.5 kB view details)

Uploaded Python 3

File details

Details for the file nested_diff-1.11.0.tar.gz.

File metadata

  • Download URL: nested_diff-1.11.0.tar.gz
  • Upload date:
  • Size: 23.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nested_diff-1.11.0.tar.gz
Algorithm Hash digest
SHA256 163835219567f3a0275eb6ae480d94c4b61c572643f4da4f1bb36906d8076b28
MD5 a2eeb21826d15789539b876e19730470
BLAKE2b-256 1df8cc0e805803eb37f49b53dcf087c0ee744d69cb1493709da9d3ac52af4f89

See more details on using hashes here.

Provenance

The following attestation bundles were made for nested_diff-1.11.0.tar.gz:

Publisher: publish.yaml on mr-mixas/Nested-Diff.py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nested_diff-1.11.0-py3-none-any.whl.

File metadata

  • Download URL: nested_diff-1.11.0-py3-none-any.whl
  • Upload date:
  • Size: 27.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nested_diff-1.11.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3e0cd2d23aa7b31c0978db0f399314eecc8acc03d171eb27ced66cc801c30e2a
MD5 99f89c0e79e6a9ea3e02ab566b869976
BLAKE2b-256 ef8edbd4b97ec8f386816f4b4e270900589cc018294e204db93102eac600bbdd

See more details on using hashes here.

Provenance

The following attestation bundles were made for nested_diff-1.11.0-py3-none-any.whl:

Publisher: publish.yaml on mr-mixas/Nested-Diff.py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.11.0 This release

2 files

1.10.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.1

2 files

1.7.0

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.2

2 files

1.3.1

2 files

1.3

2 files

1.2

2 files

1.1

2 files

1.0

2 files

0.16

2 files

0.15

2 files

0.14

2 files

0.13

2 files

0.12

2 files

0.11

2 files

0.10

2 files

0.9

2 files

0.8

2 files

0.7

2 files

0.6

2 files

0.5

2 files

0.4

2 files

0.3

2 files

0.2

2 files

0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page