Skip to main content

​
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.