XML Diff Utility

2.7.0 · active · verified Wed Apr 15

xmldiff is a Python library and command-line utility designed to create semantic differences between XML files. Unlike traditional line-by-line diff tools, it focuses on identifying structural and content changes in hierarchical XML data, often generating human-readable diffs. It is currently at version 2.7.0 and is under active development, though the library explicitly states that output formats and edit scripts might change between versions due to ongoing improvements.

Warnings

breaking xmldiff 2.0 introduced a complete, ground-up rewrite of the library. This change included a new API, different output formats, and was initially significantly slower than previous 0.x/1.x versions. Code written for 0.x/1.x is incompatible with 2.x and later.
Fix: Review the official documentation for xmldiff 2.x and rewrite code to use the new API, particularly `main.diff_files`, `diff_texts`, `diff_trees`, and `formatting` modules.
gotcha The `xmldiff` library expects `lxml` ElementTree instances when using functions like `diff_trees()`. Passing standard `xml.etree.ElementTree` objects will result in errors or unexpected behavior, requiring conversion to `lxml` types first.
Fix: Ensure that any XML trees passed to `xmldiff` functions are `lxml.etree._Element` or `lxml.etree._ElementTree` objects. Convert from `xml.etree` if necessary, e.g., by parsing XML strings directly with `lxml.etree.fromstring` or `lxml.etree.parse`.
gotcha The output (edit script or formatted XML) generated by `xmldiff` can change between minor versions. The library explicitly states that there are 'no guarantees' the output will be the same across versions, as it's under 'rapid development'. This means automated tests relying on exact output matches may break.
Fix: When writing tests or parsers for `xmldiff` output, focus on the semantic correctness of the changes rather than exact string or action sequence matches. Consider flexible parsing or asserting on the presence/absence of expected changes rather than full output equality.
gotcha Prior to version 2.6, `xmldiff` had limited or buggy handling of XML namespaces, potentially leading to 'Unknown namespace prefix' errors. While improved in 2.6, changing the URI of an existing namespace prefix is still not supported and will raise an error.
Fix: Upgrade to `xmldiff` version 2.6.0 or higher for improved namespace handling. Avoid scenarios where a namespace prefix's URI is changed between the two XML documents; instead, ensure prefixes map to consistent URIs or handle such cases manually before diffing.
gotcha The `ratio-mode` (`accurate`, `faster`, `fast`) and `--fast-match` options can significantly impact the diff's accuracy and performance. The `fast` mode, in particular, yields less accurate results, which might be acceptable for speed but could miss subtle changes.
Fix: Understand the trade-offs between performance and accuracy when selecting `ratio-mode` or `--fast-match`. For critical diffing where every change must be detected, use `accurate` mode. For large files where an approximate diff is sufficient, faster modes can be considered, but be aware of potential missed details.

Install

pip install xmldiff Install latest version

Imports

main
```
from xmldiff import main
```
Provides the primary diffing functions like `diff_files`, `diff_texts`, `diff_trees`, and `patch_file`.
formatting
```
from xmldiff import formatting
```
Contains built-in formatters like `XMLFormatter` for controlling output style.
etree
```
from lxml import etree
```
Essential for creating and manipulating XML tree objects when using `diff_trees` or processing formatter output.

Quickstart

This quickstart demonstrates how to use `xmldiff` to compare two XML files. It creates two temporary XML files, then calls `main.diff_files()` with `formatting.XMLFormatter` to get a human-readable XML output with differences marked. It also shows how to get the raw 'edit script' (list of actions) by calling `main.diff_trees()` with `lxml` Element objects directly.

import os
from lxml import etree
from xmldiff import main, formatting

# Create dummy XML files
xml1_content = """
<root>
    <item id="1">Value A</item>
    <item id="2">Value B</item>
</root>
"""
xml2_content = """
<root>
    <item id="1">Value A - Changed</item>
    <item id="3">Value C</item>
    <item id="2" status="new">Value B</item>
</root>
"""

with open('file1.xml', 'w') as f:
    f.write(xml1_content)
with open('file2.xml', 'w') as f:
    f.write(xml2_content)

# Diff two XML files and format the output as XML with diff tags
diff_output_xml = main.diff_files(
    'file1.xml',
    'file2.xml',
    formatter=formatting.XMLFormatter(pretty_print=True)
)

print("--- XML Diff ---")
print(diff_output_xml)

# Clean up dummy files
os.remove('file1.xml')
os.remove('file2.xml')

# Example using diff_trees with lxml elements directly
tree1 = etree.fromstring(xml1_content)
tree2 = etree.fromstring(xml2_content)

diff_actions = main.diff_trees(tree1, tree2)
print("\n--- Edit Script (List of Actions) ---")
for action in diff_actions:
    print(action)

view raw JSON →