File and document comparison

Compare Text Python

Compare text files with Python difflib with a reproducible example, explicit handling of whitespace and revision direction, and checks before saving the reviewed result.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Read both files using the intended text encoding and pass their line sequences to difflib.unified_diff. This produces a line-oriented report with original and revised labels. It is appropriate for plain text, source code and extracted document text; it does not parse a DOCX, PDF or XLSX binary file merely because that file has readable text somewhere inside it.

For in-memory strings, skip the file-reading stage

When your application already holds two strings, pass their split line sequences directly to unified_diff instead of saving temporary files merely to read them again. Preserve the original strings in your test fixture and label their roles in the report. The file example below makes the same operation easy to reproduce outside an application. For a single-line field, a character-level explanation may be clearer than a whole-line replacement.

Compare text files with Python difflib

from pathlib import Path
from difflib import unified_diff

original = Path("original.txt").read_text(encoding="utf-8").splitlines()
revised = Path("revised.txt").read_text(encoding="utf-8").splitlines()
difference = "\n".join(unified_diff(original, revised,
    fromfile="original.txt", tofile="revised.txt", lineterm=""))
Path("differences.diff").write_text(difference + ("\n" if difference else ""),
                                    encoding="utf-8")
print(difference or "No line-content differences")

Verify a known change

For a controlled example, put Price: 12 followed by Status: draft in the original. Change only 12 to 15 in the revised copy. The report should show the old price with a minus prefix and the new price with a plus prefix, while the status line remains context. The --- and +++ header lines label the files; they are not removed and inserted file contents. Repeat with identical files to verify that the report is empty.

Choose the right interpretation

The snippet uses splitlines(), so its contract compares line contents and deliberately ignores the exact newline encoding and a final newline. For byte-for-byte equality, compare bytes or cryptographic hashes instead. If newline preservation matters, retain line endings and use a diff format or viewer that exposes them. Large files may require a streaming or external diff implementation rather than loading both complete files into memory. A text diff of code is also not a test of what the code does.

Keep the comparison reproducible

Label the two inputs Original and Revised and keep those roles consistent. Save a copy of each before experimenting with normalization or accepting changes. A reversed comparison can show the same edit with the opposite insertion/deletion direction, which matters when a reviewer is deciding what to retain. Record the two filenames and the settings used with the result.

Test an identical pair first: it should produce no differences under the chosen contract. Then change one ordinary word, one number and one punctuation mark in the revised copy. Verify each known change before using an unfamiliar document. Include a blank line and a moved paragraph so you can see whether the method reports a move or a deletion followed by an insertion. Those presentations may describe the same underlying edit.

Decide whether spaces, capitalization and line endings matter before normalizing them. Ignoring every space can hide a meaningful change in code, a quoted value or a fixed-width record. Case folding is useful for some lookup tasks but is wrong for case-sensitive identifiers. Retain the unmodified inputs alongside any normalized copies so a surprising result can be investigated rather than explained away.

Review the complete changed region, including its surrounding context. An inserted “not,” a removed qualification or a changed unit can reverse a statement while contributing very few changed characters. Conversely, a formatter can change many lines without changing an application’s intended behavior. A difference count describes the chosen representation; it does not by itself measure importance, quality, originality or semantic equivalence.

Finish the review deliberately

For each meaningful difference, decide whether to keep the original, keep the revised version or write a new combined version. Save that reviewed result under a new filename and compare it again with the intended baseline. Do not overwrite the only original while you are still interpreting the report. Keep a short record of unresolved differences when the review is handed to another person.

Use only files you are authorized to inspect. If a web tool is involved, read its stated processing behavior and file limits before supplying confidential material. A local comparison can avoid uploading the content, but browser downloads, clipboard history and shared-device storage still need ordinary care. Clear temporary copies according to your own retention needs after the review is complete.

Primary reference

Official comparison documentation