What is the difference between pdfl compare and pdfl pixelcompare?

Two commands take two PDFs and tell you what changed. That looks like duplication until the first time they disagree — and then you find out they were never answering the same question.

pdfl compare asks what does the document say. pdfl pixelcompare asks what does the document look like.

A file can pass one and fail the other, in both directions.

pdfl compare: what the document says

It reads the text, the structure and the metadata:

pdfl compare approved_v1.pdf new_v2.pdf

The part worth knowing is how it lines the pages up. It aligns them by content, not by number. Insert one page in the middle of a contract and a naive comparison reports every page after it as changed; this one notices the insertion and keeps comparing like with like. That holds up on documents of over a thousand pages.

Each aligned pair gets a similarity score and a sample of the lines that moved, - for removed and + for added:

page 4 → 4: similarity 97.8% | -original title | +revised title

Changed metadata is a warning. Changed text is an error when it falls below the threshold you set, and a warning when it stays above.

# Ignore case, spacing and dates — useful when the issue date is
# regenerated on every export and is not the thing under review
pdfl compare approved_v1.pdf new_v2.pdf --normalize --ignore-dates

# Allow up to 1% difference, and produce something a person can read
pdfl compare v1.pdf v2.pdf --similarity-threshold 99 \
  --output html --output-file diff.html

pdfl pixelcompare: what the document looks like

It renders both files and compares the pages as images:

pdfl pixelcompare approved.pdf reprint.pdf

One finding per page that changed, with how much of it differs and in how many separate places:

page 7: 0.51% of the pixels differ, in 29 area(s)

It compensates for a global shift first, because a file exported again from the same source often lands a pixel or two off, and without that every letter edge would count as a difference:

page 3: 2.10% of the pixels differ, in 44 area(s) (aligned by 2, -1 px)

And it can write somewhere to look:

pdfl pixelcompare approved.pdf reprint.pdf --viewer diff/

That folder holds the pages, the differences and an index.html — no server, nothing to install. Red is ink that is gone, green is ink that is new, blue is the same weight in a different colour.

Where they disagree

The text is identical and the file is wrong. A logo nudged two millimetres. A hairline rule that vanished. A spot colour swapped for a CMYK build of it. compare reports a perfect match on all three, because not one character moved. pixelcompare catches all three.

The file looks identical and the text is wrong. The title in the metadata was replaced, or an author field was rewritten. Nothing on the page moves a pixel, so pixelcompare sees two identical documents. compare reports the change.

Neither is a superset of the other. That is the whole point.

Four situations, and what to run

A contract came back from legal. You need to know what the wording says now compared with what it said before. The layout will have reflowed and you do not care.

pdfl compare contract_v3.pdf contract_v4.pdf --ignore-dates \
  --output html --output-file review.html

A reprint arrived from the supplier. Nothing at all should look different from the proof that was approved. Whether the text is byte-identical is beside the point — what goes on paper is the question.

pdfl pixelcompare approved.pdf reprint.pdf --viewer diff/

The same document, exported by a different tool. A supplier switched software. The words have to survive intact, and the appearance is likely to drift a little. This needs both, and they are checking different promises:

pdfl compare old_export.pdf new_export.pdf --normalize
pdfl pixelcompare old_export.pdf new_export.pdf --max-diff 0.1 --viewer diff/

A regulated label or insert. The warning text is required by law and the layout was approved by someone who signed for it. Both are binding, so both get checked — and the viewer folder is what you attach to the approval.

pdfl compare approved.pdf press_file.pdf
pdfl pixelcompare approved.pdf press_file.pdf --viewer evidence/

Both at once, as a gate

Each command exits with a code, so a script can decide without reading anything. pixelcompare uses 0 for no page over the tolerance, 2 when one is over it, and 10 when a file could not be read; compare follows the convention every validating command uses — 0 passed, 1 warnings, 2 errors, 10 unreadable.

#!/bin/sh
# Both promises, one gate: the words and the appearance.
set -e

pdfl compare approved.pdf candidate.pdf --output-file text-diff.json || {
  echo "the wording changed — see text-diff.json"
  exit 1
}

pdfl pixelcompare approved.pdf candidate.pdf --max-diff 0.05 --viewer diff/ || {
  echo "it does not look the same — open diff/index.html"
  exit 1
}

echo "same words, same appearance"

Which one, in one line

The question you are asking	The command
Did the wording change?	pdfl compare
Did the metadata change?	pdfl compare
Was a page inserted or removed?	pdfl compare
Did anything move, vanish or change colour?	pdfl pixelcompare
Does it still print the same?	pdfl pixelcompare
Is this the file that was approved?	both

Where to look next

The CLI chapter documents every option of both, and the recipes put them inside complete workflows. There is also a post here on pixel-by-pixel comparison and what a wrong file costs once it is on the press.