diff-pdf

Compare PDFs, indicating changes using return codes (0 = no difference, 1 = PDFs differ)

$ diff-pdf [path/to/a.pdf] [path/to/b.pdf]

$ diff-pdf --output-diff=[path/to/diff.pdf] [path/to/a.pdf] [path/to/b.pdf]

$ diff-pdf --view [path/to/a.pdf] [path/to/b.pdf]

diff-pdf [OPTION...] LEFT RIGHT

--help
    Show this help message and exit

--version
    Show program's version number and exit

-v, --verbose
    Print verbose messages to stderr

-p RANGE, --pages=RANGE
    Pages to use for comparison (default: all)

-o DIR, --output=DIR
    Directory to place output files in

-l LABEL, --label=LABEL
    Label to distinguish output files from different runs

--show-only
    Generate images only and show them (no differences)

--viewer=PROG
    Program to show images (default: xdg-open)

-A, --auto-color-depth
    Automatically determine color depth

-d N, --color-depth=N
    Bits per channel (1-16, default: 8)

-t TOL, --tolerance=TOL
    Max tolerated difference per channel (default: 110)

-m, --metrics
    Print page metrics (size, MD5) instead of images

diff-pdf is a command-line tool for visually comparing two PDF documents. It renders pages from both PDFs into high-resolution PNG images using pdftoppm from Poppler, then computes pixel-wise differences to highlight changes, additions, or deletions. Differing regions appear in red, with options for tolerance to ignore minor rendering variations like anti-aliasing.

Ideal for quality assurance in document workflows, such as verifying generated reports, contracts, or invoices where layout, fonts, or images matter more than text. Output includes annotated difference images, original renders, and optional metrics like page size or checksums. Users can limit to specific pages, customize image depth, or auto-launch results in an image viewer.

Unlike text-based diffs, it catches visual discrepancies from formatting shifts or embedded graphics, making it essential for CI/CD pipelines testing PDF outputs across platforms.

Requires poppler-utils; high-res or large PDFs use much disk/CPU. Rendering differences (fonts, DPI) may cause false positives. PDFs must have matching page counts for full comparison.

Needs poppler-utils for rendering; ImageMagick optional for viewing.

diff-pdf -p 1-5 -o diffs/ doc1.pdf doc2.pdf
Compare pages 1-5, output to diffs/ directory.

Created by Vladimir Slavik in 2011 as open-source C++ tool (GitHub: vslavik/diff-pdf). Gained popularity for PDF QA in automation; regular updates improve Poppler compatibility and add features like metrics output.

pdftoppm(1), diff(1), xdg-open(1), diffpdf(1)