Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DilwoarH/pdf-visual-regression/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before installing the PDF visual regression tester, ensure you have the following:
  • Python 3.7 or higher: The tool requires Python 3 with pip installed
  • pip: Python package installer (usually comes with Python)
  • Git: For cloning the repository (optional if downloading as ZIP)
It is strongly recommended to use a virtual environment to avoid conflicts with other Python packages on your system.

​
Installation steps

1

Clone the repository

First, clone the repository to your local machine:
git clone <your-repository-url>
cd pdf-visual-regression
Replace <your-repository-url> with the actual URL of the repository.
2

Create a virtual environment

Create and activate a Python virtual environment to isolate dependencies:
python3 -m venv venv
source venv/bin/activate
After activation, your terminal prompt should show (venv) indicating the virtual environment is active.
3

Install dependencies

Install all required Python packages using pip:
pip install -r requirements.txt
This will install the following dependencies:
  • PyMuPDF: PDF rendering and manipulation
  • scikit-image: Image comparison algorithms
  • Pillow: Image processing
  • numpy: Numerical operations
  • reportlab: PDF generation (for testing)

​
Alternative installation with Makefile

If you prefer using Make, you can install dependencies with a single command: 
make install
This runs python3 -m pip install -r requirements.txt automatically.
Make sure your virtual environment is activated before running make install to avoid installing packages globally.

​
Verify installation

To verify that the tool is installed correctly, run the help command: 
python pdf_visual_diff.py --help
You should see output similar to: 
usage: pdf_visual_diff.py [-h] [--output OUTPUT] [--threshold THRESHOLD] pdf1 pdf2

Compare two PDFs for visual differences.

positional arguments:
  pdf1                  Path to the first PDF file.
  pdf2                  Path to the second PDF file.

optional arguments:
  -h, --help            show this help message and exit
  --output OUTPUT       Directory to save difference images.
  --threshold THRESHOLD
                        Similarity threshold for SSIM (0.0 to 1.0).

​
Environment-specific notes

​
Linux

On some Linux distributions, you may need to install additional system dependencies: 
sudo apt-get update
sudo apt-get install python3-dev python3-pip

​
macOS

Ensure you have Python 3 installed via Homebrew: 
brew install python3

​
Windows

Make sure Python is added to your PATH during installation. You can verify by running: 
python --version
On Windows, you may need to use python instead of python3 in commands.

​
Troubleshooting

This means PyMuPDF is not installed correctly. Try:
pip install --upgrade PyMuPDF
Make sure you’re using a virtual environment or install with the --user flag:
pip install --user -r requirements.txt
Verify you’re using Python 3.7 or higher:
python3 --version
If your version is older, consider upgrading Python or using pyenv to manage multiple versions.

​
Next steps

Now that you have the tool installed, proceed to the Quickstart guide to run your first PDF comparison.

Build docs developers (and LLMs) love

Get started for freeTalk to us