diff-pdf: visual comparison of two PDFs from the command line, with a GUI mode

The problem diff-pdf solves, and the people it fits

Two PDFs that should be identical rarely are. A rebuilt document may differ only in embedded timestamps, a translated release may shift text by a few points, and a converted file may move a figure by a pixel. Text-based diff tools cannot answer the question that matters here: do these two files look the same on the page? diff-pdf answers exactly that. It takes two PDF files as arguments and, by default, its only output is its return code: 0 when there are no differences and 1 when the two PDFs differ. That single behaviour makes it usable inside a shell script or a CI job where a human never looks at the output.

The intended audience is narrow and the README says so. It opens with a note that the repository is provided as-is, that the code is not being actively developed, and that pull requests are welcome but support, feature requests and fixes should not be expected. The note ends bluntly: if you are not a developer or willing to get your hands dirty, this tool is probably not for you. That is not marketing modesty. It is an accurate description of a small C++ program whose value comes from doing one comparison well and returning an exit status.

How the comparison works: Poppler renders, Cairo draws, wxWidgets shows

The dependency list tells you the architecture. diff-pdf requires wxWidgets 3.0 or newer, Cairo 1.4 or newer and Poppler 0.10 or newer. Poppler is the PDF rendering library, so the pages of both input files are rasterised rather than compared as text or object trees. Cairo provides the drawing layer used to produce output, and wxWidgets supplies the windowing toolkit behind the --view mode. The repository layout matches this: diff-pdf.cpp holds the main program, bmpviewer.cpp and bmpviewer.h implement the bitmap viewer, and gutter.cpp and gutter.h handle the layout between the two rendered pages.

Because the comparison is visual, the tool is sensitive to rendering differences and blind to meaning. Two files with different text but identical glyph positions render identically; two files with identical text but a different embedded font may not. The README does not document how tolerance is handled or whether any threshold exists, so treat the comparison as a pixel-level render check rather than a semantic one. The --view mode exists precisely because that strictness produces false alarms: the README states you can shift the two pages relative to each other with Ctrl-arrows (Cmd-arrows on macOS), which it describes as useful for identifying translation-only differences. Ctrl+< and Ctrl+> show the left and right documents respectively, and Ctrl+D returns to the diff view.

Installing diff-pdf and running a first comparison

On Windows the README points to a precompiled ZIP archive attached to the latest release, which contains everything needed to run the tool and works from any place you unpack it. If you use Chocolatey, the README gives this command, which installs diff-pdf on Windows:

choco install diff-pdf

On macOS, Homebrew and MacPorts both carry it. The README lists these two commands:

brew install diff-pdf

port install diff-pdf

On Fedora and CentOS 8 the package is in the distribution repositories:

sudo dnf install diff-pdf

Precompiled openSUSE packages are available from the openSUSE build service according to the README.

Once installed, the basic invocation takes two files. The default output is only the return code, so a first useful run is to compare two documents and check the exit status, where 0 means no differences and 1 means the files differ. To get something you can look at, pass --output-diff, which the README shows producing a PDF with visually highlighted differences:

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

For interactive inspection, --view opens a window that lets you view the files' pages and zoom in on details:

diff-pdf --view a.pdf b.pdf

The README directs readers to the output of diff-pdf --help for the complete list of options, which is the right place to check what your particular build supports before scripting anything.

Building from source and the platform cost that comes with it

The build system uses Automake, so a Unix or Unix-like environment is required, with Cygwin or MSYS named as the Windows route. The standard sequence is bootstrap, configure, make, make install. The README notes that the bootstrap step is only needed when building sources checked out from version control, where configure and Makefile.in are missing.

Dependency installation is where the platforms diverge. On Ubuntu 24.04 or Debian 12 and newer the README gives a two-line apt-get install covering make, automake, g++, libpoppler-glib-dev, poppler-utils and libwxgtk3.2-dev; older Ubuntu and Debian releases use libwxgtk3.0-gtk3-dev instead. On CentOS the route is a yum groupinstall of Development Tools plus wxGTK, wxGTK-devel, poppler-glib and poppler-glib-devel. On macOS you install the Xcode Command Line Tools with xcode-select --install, then use Homebrew or MacPorts for automake, autoconf, wxmac or wxWidgets-3.0, poppler, cairo and pkg-config.

Windows is the expensive case. The README states that many more libraries are required there, because none of the libraries Cairo and Poppler use are normally available, and that transitive coverage at the time of writing included fontconfig, freetype, glib, libpng, pixman, gettext, libiconv, libjpeg and zlib. The MSYS2 path adds pacman and pacboy steps to install automake, autoconf, pkg-config, make, zip, pactoys, gcc, poppler and wxWidgets, after which the build follows the same bootstrap, configure, make sequence. A make windows-dist target produces a ZIP archive with all the DLLs. Unless you need to modify the code, the precompiled Windows archive avoids this entirely.

Where diff-pdf is the wrong tool

The README's own note is the first limitation: no support, no feature requests, no fixes. The last push to the repository was on 2026-03-28, the same date as the v0.5.3 release, and the two releases before that were v0.5.2 in January 2024 and v0.5.1 in April 2023. That pattern suggests occasional maintenance rather than a project with a roadmap, and the README's as-is statement should be read literally.

The second limitation is the comparison model. Visual comparison cannot tell you what changed in the text layer, so if you need to know that a clause was reworded, a value changed from 10 to 12, or a table cell was edited, diff-pdf will report a difference but not its nature. It is also the wrong instrument when the two documents are expected to differ in layout by design, because every reflowed line registers as a difference. And it is a poor fit for automated pipelines that need machine-readable output: the default interface is a return code, and while --output-diff produces a PDF, the README does not describe any structured report format. If your build system needs to know which page and which region changed, you will be reading a rendered image, not parsing a data structure.

Alternatives and how their approach differs

The closest alternative in the same family is pdftotext plus a text diff, which ships with poppler-utils, itself listed in the README's Ubuntu and Debian dependency commands. That approach extracts the text layer from each PDF and compares the strings, so it answers what changed in words and ignores rendering entirely. diff-pdf does the opposite: it renders both pages and compares what a reader would see. Neither is a superset of the other. A document where a font substitution changes every glyph shape but no character will pass a text diff and fail diff-pdf; a document where a paragraph is rewritten but the layout is identical will fail a text diff and may pass diff-pdf's visual comparison only if the glyphs land differently.

For teams that want a hosted service rather than a local binary, the search data around this project shows people looking for online PDF comparison and for Diffchecker, a web tool used for comparing documents. That is a different trade-off: you upload the files, and you get a browser view. diff-pdf keeps the files local, runs from a shell, and returns an exit code, which is what makes it embeddable in a build. There is no diff-pdf server component in the repository layout; the top-level entries are source files, build files, icons and a win32 directory.

Licence, upgrade cost and what to check before adopting

diff-pdf is released under GPL-2.0. The repository carries COPYING and COPYING.icons files, which is consistent with a GPL-2.0 code licence plus a separate notice for the bundled icon assets. If you link or redistribute diff-pdf inside a proprietary product, the GPL-2.0 obligations are the thing to examine with your own counsel; this article does not give legal advice. Running the binary as a separate command-line tool from a build script is a different situation from embedding its code, and the distinction matters.

Upgrade cost is low in one sense and unpredictable in another. The version history shows v0.5.1, v0.5.2 and v0.5.3 spanning 2023 to 2026, so releases are infrequent and there is no evidence of breaking interface churn. The README documents a small, stable surface: two file arguments, --output-diff, --view, and the --help output for everything else. The unpredictable part is dependency drift. A build requires wxWidgets, Cairo and Poppler at the minimum versions listed, and the README already distinguishes libwxgtk3.2-dev on newer Debian and Ubuntu from libwxgtk3.0-gtk3-dev on older releases. On a distribution that moves to a newer wxWidgets or Poppler, a source build may need adjustment, and given the as-is note, that adjustment is yours to make and to submit as a pull request.

Editorial conclusion

Adopt diff-pdf when you need a scriptable pass or fail check on two PDFs, or a side-by-side GUI for translation-only differences, and you can install Poppler and wxWidgets or use the packaged binaries. Do not adopt it if you need a maintained product with feature requests, since the README states the repository is provided as-is and the code is not being actively developed. Before relying on it, verify that the packaged version you install matches the option set you need by running diff-pdf --help, and confirm your build links wxWidgets 3.0 or newer, Cairo 1.4 or newer and Poppler 0.10 or newer.

Frequently asked questions

Official sources

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