Compare two PDF files offline with diff-pdf

Install from the project’s documented route

The repository lists platform-specific installation options, including Homebrew for macOS and a packaged Windows release. Review the current instructions and choose the supported route for your machine. This guide describes the commands; NarrowTools has not benchmarked the program on your documents.

Generate a difference file

After installation, supply the two local filenames and a separate output path. The input documents remain distinct from the generated comparison.

diff-pdf --output-diff=changes.pdf old.pdf new.pdf

The documented return code is 0 when no differences are found and 1 when the PDFs differ. A script must distinguish a detected difference from an operational failure.

Use the visual viewer when alignment matters

The --view option opens the project’s comparison viewer. A shifted page can make many elements appear different even when the text is unchanged. The repository documents alignment controls in the viewer; consult its help for the installed build rather than guessing from the appearance of the difference PDF.

diff-pdf --view old.pdf new.pdf

Review the meaning of the difference

Visual comparison can flag changed pages, logos, text positions, or missing objects. It does not understand whether a price is per case, a paragraph changes a commercial condition, or an item’s identifier was corrected. For supplier data, compare the extracted fields separately and use the PDF difference to find pages worth reviewing.

Use a small repeatable sample

Keep one identical pair, one pair with a deliberate text edit, and one pair with a layout shift. Run those after installation or an environment change so you know how the tool reports each case. If the build cannot handle a document reliably, keep it in a manual review queue rather than interpreting an empty or failed result as approval.