How to Compare Two PDF Versions

Comparing two versions of a PDF: how to read the result

The other side sent "the same draft with minor edits". The question is always the same: where exactly are the edits, and has anything appeared that nobody mentioned. Reading both documents through takes an hour and works badly: the eye skips a changed figure and finds differences where a line simply shifted.

The tool answers that question in two different ways at once, and it helps to understand the difference before you start.

Two reports answering different questions

Both are built by default, and the text one comes first in the result list. That is a sensible pair: the text report is easy to paste into an email and discuss line by line, the visual one is for opening next to the original and pointing at.

If the visual report could not be built and you asked for both, the job does not fail: you get the text report plus a separate warning naming the reason. That is deliberate, because a document the renderer could not handle usually still yields to text comparison.

Four colours and what each one means

The visual report marks pages with coloured frames, and each colour carries its own kind of change.

There is a fifth marker as well, a solid wash with its own colour and its own legend row. It marks differences outside the text: in an image, a rule, a table cell background, a colour. That is not a markup error but a different kind of comparison, described below.

Why "moved" is not the same as "changed"

Here is where the tool does its real work. A naive comparison matches pages line by line, and inserting a single paragraph at the top makes every line below it "changed", because each one shifted along.

This comparison works differently: a page is broken into text blocks, and blocks are matched between versions by content rather than by position. A paragraph that simply slid down because of an insertion above is recognised as the same one and is not marked at all.

The blue "moved" marker appears only when the relocation is an edit rather than a consequence of reflow. A contract clause that travelled from section three to section seven comes out blue. The same clause pushed two centimetres down by a sentence added above stays unmarked.

The practical meaning is simple: the count in the summary reflects the number of real edits, not the scale of the reflow.

What gets compared besides text

Everything that is not text is compared pixel by pixel: pictures, logos, table rules, fills, colour.

An important detail: the pixel comparison runs only outside the text blocks. That is deliberate, so one and the same edit is not counted twice, first as changed text and then as changed pixels in the same spot.

Which explains a common puzzle: "half the page is highlighted and the summary says zero changes". It means the text content did not change but something else did: a different version of a logo, a different shade of fill, a picture re-saved with different compression. Sometimes that matters, sometimes it is a side effect of the file being re-exported from a different editor.

How to run the comparison

1. Open compare-pdf and upload exactly two files. 2. Make sure the older version comes first: the order decides what counts as added and what as removed. 3. Leave both reports on if you are not sure which one you will need. 4. Run the job and download the result. 5. Start with the text report: it shows the substance of the edits. Open the visual one for the places where the text alone is unclear.

The file order deserves separate attention. The tool does not know which version is newer and decides by position: the first file is "before", the second is "after". A swapped order gives you a mirrored report where additions show up as deletions.

Comparing scans

A scan holds no text, so a text report over two scans comes out empty, and that is not a failure.

The visual comparison still runs: the pixel half needs no text layer. For documents where you need to spot a substituted page or a line written in by hand, that is often enough.

If you need the text breakdown specifically, both documents have to go through ocr-pdf first. Bear in mind that recognised text contains errors, so part of the differences in the report will be discrepancies of recognition rather than of the documents.

The same subject gets its own warning: if text could not be reliably extracted from some pages, the result lists their numbers. Those pages were not compared as text and may be hiding real differences.

What the settings actually change

The comparison mode decides how text is extracted for the text report: text only, or text together with its spacing. The second mode notices changes in indentation and alignment, and it has no effect on the visual report at all.

Ignoring whitespace is on by default and drops from the report differences made up only of spaces and line breaks.

Those two settings conflict, and the tool says so honestly. In the text-and-layout mode whitespace is the layout signal, so it cannot be ignored, and the setting silently stops applying to the text report. Instead of silence you get a warning. The visual report, meanwhile, keeps honouring the whitespace setting.

The limits

The visual report is built for documents of no more than a hundred pages: every page has to be rendered twice and laid into a spread, which is expensive. Text comparison has no such ceiling.

If the documents are longer, the sensible move is to compare by section rather than whole: pull the ranges you need out of both versions with extract-pages and compare the parts.

A document protected by an open password cannot be compared: the content is encrypted. The password has to come off first.

And last: comparison answers the question "what changed", not "is this edit legitimate". Read the report as a list of places to check, not as a conclusion.