Open-source project
vslavik/diff-pdf avatar
vslavik/diff-pdf

diff-pdf renders the difference instead of listing it

A simple tool for visually comparing two PDF files

4,344 stars265 forksC++GPL-2.0

At a glance

What is it?
diff-pdf is a C++ command line tool that rasterises two PDFs through Poppler and Cairo, can write a PDF with the differences visually highlighted, and gives you exit code 1 so a build script can act on it. It is a visual comparator, not a text differ, and it says so in its own README.
Who is it for?
Adopt diff-pdf if your failures are layout shifts, moved tables and redrawn charts, cases where text extraction would report two documents as equal and you need a return code to fail a build on. Skip it if you need per-character change lists, a reviewable text diff that fits in a pull request comment, or a project whose maintainers answer issues, because the README declines support outright.
Can I use it commercially?
Yes, with conditions. GPL-2.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • vslavik/diff-pdf4,344 ★ · +24
Star history
Repository2026-09-232026-11-15
vslavik/diff-pdf4.3k4.3k

24 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The return code is the whole interface, and the overlay is optional

Most tools of this kind are libraries you call. diff-pdf is an executable whose default output is a number. Point it at two files and it returns 0 when they match, 1 when they differ, and writes nothing to stdout. That shape is what makes it fit into a build: two file paths in a shell script become a test assertion without a wrapper.

bash
$ diff-pdf --output-diff=diff.pdf a.pdf b.pdf

Pass --output-diff and you get a third file, a PDF with the differences visually highlighted. Nothing else changes about the invocation. Two input paths, one output path, and a return code that stays the same either way.

That thin surface has a cost. A diff file tells you where the pages changed, not which word changed. If a paragraph is reflowed, the overlay covers the paragraph. Anyone who needs the old sentence beside the new one has to open both PDFs by hand afterwards. The `--view` mode exists for exactly that kind of reading, and the README is candid that if you are not a developer or not willing to get your hands dirty, the tool is probably not for you.

Rasterisation through Poppler and Cairo, not text extraction

diff-pdf does not read the text layer and it does not diff the content streams. It renders both documents to a bitmap through Poppler, compares the pixels, and draws the results with Cairo. That choice decides everything about its behaviour, including where it stops working.

A pure text diff would report two PDFs as identical when the same words sit at different coordinates, and would report them as different when a timestamp in the metadata changes. A pixel comparison inverts both cases. Repositioned text becomes a difference. A metadata-only edit does not.

The cost sits on the other side. Two documents whose text matches but whose font substitution differs can rasterise differently, so a machine missing the embedded typeface can report a difference that is not in the content. The README requires Poppler >= 0.10 and Cairo >= 1.4, and says nothing about how font substitution is handled, so treat a difference report on a font-heavy document as needing a human look before you treat it as a regression.

The --view GUI exists for translation-only changes

`--view` opens a wxWidgets window with both documents and lets you slide one page against the other with Ctrl-arrows, or Cmd-arrows on macOS.

bash
$ diff-pdf --view a.pdf b.pdf

The README gives the reason: this is useful for identifying translation-only differences, where every glyph changed position but the words did not change. A pixel diff lights up the entire text block in that case. Sliding the two pages until the unchanged furniture lines up is how you tell a genuine edit from a wholesale re-layout.

Two keys step through to the left and right documents, and Ctrl+D returns to the diff view. There is no keyboard shortcut documented for jumping between differing pages, and no headless equivalent of the offset control, so this part of the workflow cannot be scripted from the README's options alone. It is a reading tool with a comparison mode bolted on, not the other way round.

Four package managers, and a build that needs three C libraries

Binaries exist through several channels. Windows users get a ZIP archive of precompiled binaries that runs from wherever it is unpacked. Elsewhere the usual managers cover it.

bash
$ brew install diff-pdf

The same tool is available as `choco install diff-pdf` on Windows, `port install diff-pdf` under MacPorts, and `sudo dnf install diff-pdf` on Fedora and CentOS 8, with a separate openSUSE build referenced from software.opensuse.org. Anyone on Ubuntu or Debian is expected to build it, because no package is named for those distributions.

Building from source needs wxWidgets >= 3.0, Cairo >= 1.4 and Poppler >= 0.10, then the usual Automake sequence.

bash
$ ./bootstrap
$ ./configure
$ make
$ make install

On Ubuntu 24.04 or Debian 12 the dependencies are two apt lines.

bash
$ sudo apt-get install make automake g++
sudo apt-get install libpoppler-glib-dev poppler-utils libwxgtk3.2-dev

Older Ubuntu and Debian need `libwxgtk3.0-gtk3-dev` in place of the 3.2 package. The bootstrap step is only needed from a version control checkout, since it generates the missing `configure` and `Makefile.in`. `make install` covers installation on Unix. On Windows installation is skipped entirely: copy the files, or build a ZIP with `make windows-dist`.

The README rules out support before it rules anything in

The first line of the project states that the repository is provided as-is and that the code is not being actively developed. It then invites pull requests while saying explicitly that no support should be expected, including feature requests or fixes. It closes by telling non developers that the tool is not aimed at them.

That framing is unusual enough to be worth taking at face value rather than reading as boilerplate. The last push was on 2026-10-23, and the repository is not archived, so the code is there to read and fork, but no one is on the other end of an issue.

A contradiction worth noting: the same page that declines all support still asks for contributions and offers to merge them. Read that as an invitation to send a patch, not as a maintenance commitment you can plan a dependency upgrade around. The licence is GPL-2.0, a fact that matters for anyone considering shipping a modified build inside a closed product and not at all for someone running the command in CI.

Where a text differ wins, and where this one does not

The real alternative is not another visual comparator, it is a text extraction tool such as pdftotext from Poppler, followed by a line differ. The approach differs at the root. Extraction compares characters in reading order and tells you which line changed. diff-pdf compares rendered pixels and tells you which rectangle changed.

Choose the text route when the change is lexical: a swapped figure, a renamed variable in a code listing, a missing disclaimer. The output is a reviewable text diff that fits in a comment on a pull request, and it costs nothing at render time.

Choose diff-pdf when the change is spatial: a table cell that moved, a chart redrawn, a logo replaced, a font size changed on a heading. Text extraction reports those documents as equal because the character stream matches. Only a rendered comparison surfaces them.

There is also a version control angle. A PDF diff is only meaningful against a previous rendering, so storing two copies of every artefact doubles storage, and the comparison depends on the machine that rasterised it. A tool that hashes the extracted text sidesteps both. That is the trade you are making, not a quality difference between two PDF comparators.

One flag separates the two uses of the same invocation

The part of diff-pdf that survives contact with a real repository is the return code. Nothing more is needed to make a build fail on a changed document. Run the two-file comparison between a regenerated artefact and the copy from the previous build and you get a pass or a fail with no human in the loop.

Add the output flag used above and the failing run also leaves behind a file you can attach to the build, which is the whole workflow in one command. Drop it and the tool writes nothing at all, which is what you want in a script that only needs the verdict.

What breaks first is not the comparison but the baseline. Rasterisation is deterministic only on a machine with the same font set and the same library versions, so a baseline generated on a developer laptop and a comparison run on a CI container can disagree about fonts the document never embedded. The README does not document a flag for font substitution, a resolution setting, or an anti-aliasing control, and it points to `diff-pdf --help` for the complete list of options. Treat a first red build as a question about the rendering environment before you treat it as a document regression.

Editorial conclusion

Adopt diff-pdf if your failures are layout shifts, moved tables and redrawn charts, cases where text extraction would report two documents as equal and you need a return code to fail a build on. Skip it if you need per-character change lists, a reviewable text diff that fits in a pull request comment, or a project whose maintainers answer issues, because the README declines support outright. Before anything else, check how your own documents rasterise on the machine that will run the comparison: font substitution, anti-aliasing and library versions all change which pixels differ, and the README does not document options for pinning them, so check `diff-pdf --help`.

Frequently asked questions

What is diff-pdf?

It is a command line tool for visually comparing two PDF files, written in C++. By default its only output is a return code, 0 when the files match and 1 when they differ.

Is there a way to diff PDFs?

diff-pdf exists for that purpose and it compares documents by rendering them rather than by comparing their text. The result is a visual overlay showing which regions changed.

How do you install diff-pdf?

Precompiled binaries are offered for Windows as a ZIP attached to the latest release, and package managers cover MacPorts, Homebrew, Fedora, CentOS 8 and openSUSE. On Ubuntu and Debian the project documents building from source with Automake.

How do you use diff-pdf to compare two files?

Pass the two files as arguments to get a return code, add --output-diff to write a PDF with the differences highlighted, or add --view to open a window where the pages can be zoomed and shifted against each other with Ctrl-arrows.

How do you diff PDF files with diff-pdf?

The command takes two input files, for example `diff-pdf --output-diff=diff.pdf a.pdf b.pdf`. The written diff PDF shows the differences visually highlighted.

Official sources

  1. License: GPL-2.0
  2. Project website
  3. README
  4. Releases
  5. vslavik/diff-pdf on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/vslavik-diff-pdf.svg)](https://hysenlabs.com/projects/vslavik-diff-pdf)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/vslavik-diff-pdf.svg)](https://hysenlabs.com/projects/vslavik-diff-pdf)

Was this useful?