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

# Installation

> Install the PDF visual regression testing tool and verify your setup

## 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)

<Note>
  It is strongly recommended to use a virtual environment to avoid conflicts with other Python packages on your system.
</Note>

## Installation steps

<Steps>
  <Step title="Clone the repository">
    First, clone the repository to your local machine:

    ```bash theme={null}
    git clone <your-repository-url>
    cd pdf-visual-regression
    ```

    <Info>
      Replace `<your-repository-url>` with the actual URL of the repository.
    </Info>
  </Step>

  <Step title="Create a virtual environment">
    Create and activate a Python virtual environment to isolate dependencies:

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      python3 -m venv venv
      source venv/bin/activate
      ```

      ```bash Windows (Command Prompt) theme={null}
      python -m venv venv
      venv\Scripts\activate.bat
      ```

      ```bash Windows (PowerShell) theme={null}
      python -m venv venv
      venv\Scripts\Activate.ps1
      ```
    </CodeGroup>

    After activation, your terminal prompt should show `(venv)` indicating the virtual environment is active.
  </Step>

  <Step title="Install dependencies">
    Install all required Python packages using pip:

    ```bash theme={null}
    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)
  </Step>
</Steps>

## Alternative installation with Makefile

If you prefer using Make, you can install dependencies with a single command:

```bash theme={null}
make install
```

This runs `python3 -m pip install -r requirements.txt` automatically.

<Warning>
  Make sure your virtual environment is activated before running `make install` to avoid installing packages globally.
</Warning>

## Verify installation

To verify that the tool is installed correctly, run the help command:

```bash theme={null}
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:

```bash theme={null}
sudo apt-get update
sudo apt-get install python3-dev python3-pip
```

### macOS

Ensure you have Python 3 installed via Homebrew:

```bash theme={null}
brew install python3
```

### Windows

Make sure Python is added to your PATH during installation. You can verify by running:

```bash theme={null}
python --version
```

<Note>
  On Windows, you may need to use `python` instead of `python3` in commands.
</Note>

## Troubleshooting

<Accordion title="ImportError: No module named 'fitz'">
  This means PyMuPDF is not installed correctly. Try:

  ```bash theme={null}
  pip install --upgrade PyMuPDF
  ```
</Accordion>

<Accordion title="Permission denied errors">
  Make sure you're using a virtual environment or install with the `--user` flag:

  ```bash theme={null}
  pip install --user -r requirements.txt
  ```
</Accordion>

<Accordion title="Python version issues">
  Verify you're using Python 3.7 or higher:

  ```bash theme={null}
  python3 --version
  ```

  If your version is older, consider upgrading Python or using pyenv to manage multiple versions.
</Accordion>

## Next steps

Now that you have the tool installed, proceed to the [Quickstart](/quickstart) guide to run your first PDF comparison.