Installation

This guide covers everything you need to install and configure PatchCore for industrial anomaly detection.

System Requirements

Python Version

Python 3.8 or higherResults were computed using Python 3.8

GPU Memory

11GB VRAM minimumRequired for most experiments at standard image sizes

Operating System

Linux (recommended)Also works on macOS and Windows with WSL2

CUDA Support

CUDA 10.2 or higherOptional but strongly recommended for GPU acceleration

Larger input images will require more GPU memory. If you plan to use 320x320 images or larger, ensure you have at least 16GB of VRAM.

Installation Steps

Clone the Repository

First, clone the PatchCore repository:

git clone https://github.com/amazon-science/patchcore-inspection.git
cd patchcore-inspection

Create Virtual Environment (Recommended)

Create an isolated Python environment:

python -m venv patchcore-env
source patchcore-env/bin/activate  # On Linux/macOS
# or
patchcore-env\Scripts\activate  # On Windows

conda create -n patchcore python=3.8
conda activate patchcore

Install Core Dependencies

Install all required packages from requirements.txt:

pip install -r requirements.txt

This installs:

Core Dependencies

click >= 8.0.3: Command-line interface framework
torch >= 1.10.0: PyTorch deep learning framework
torchvision >= 0.11.1: Pre-trained models and image transforms
pretrainedmodels >= 0.7.4: Additional backbone architectures

Scientific Computing

scikit-image >= 0.18.3: Image processing
scikit-learn >= 1.0.1: Machine learning utilities
scipy >= 1.7.1: Scientific computing
numpy: Numerical operations (installed as dependency)

Visualization & Utilities

matplotlib >= 3.5.0: Plotting and visualization
pillow >= 8.4.0: Image loading and processing
tqdm >= 4.62.3: Progress bars

Similarity Search

faiss-cpu: CPU-based similarity search (default)
faiss-gpu: GPU-accelerated similarity search (optional)

Choose FAISS Backend

By default, requirements.txt installs faiss-cpu. For significantly faster training and inference, install the GPU version:

pip uninstall faiss-cpu -y
pip install faiss-gpu

# Already installed via requirements.txt
# Use this if you don't have a CUDA-compatible GPU

GPU vs CPU Performance:

faiss-gpu: 10-50x faster similarity search, requires CUDA
faiss-cpu: Works everywhere but significantly slower

When using CPU FAISS, remove the --faiss_on_gpu flag from training commands.

Set PYTHONPATH

PatchCore requires the src directory to be in your Python path:

export PYTHONPATH=src:$PYTHONPATH

echo 'export PYTHONPATH="'$(pwd)'/src:$PYTHONPATH"' >> ~/.bashrc
source ~/.bashrc

$env:PYTHONPATH="src;$env:PYTHONPATH"

Alternative: Use env prefix

Instead of setting PYTHONPATH globally, you can prefix each command:

env PYTHONPATH=src python bin/run_patchcore.py ...

Verify Installation

Test that all dependencies are correctly installed:

python -c "import torch; import patchcore; print('✓ Installation successful!')"

Check PyTorch CUDA availability:

python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

Expected output:

CUDA available: True

Optional: Install from setup.py

For a more permanent installation, you can install PatchCore as a package:

pip install -e .

This uses the setup.py file which:

Installs all dependencies from requirements.txt
Makes the patchcore package importable from anywhere
Allows editable development (-e flag)

View setup.py

from pathlib import Path
from setuptools import find_packages, setup

package_path = Path(__file__).parent
version_path = Path(__file__).parent.joinpath(f"src/patchcore/VERSION")
version = version_path.read_text().strip()
install_requires = (
    Path(__file__).parent.joinpath("requirements.txt").read_text().splitlines()
)

setup(
    name="patchcore",
    version=version,
    install_requires=install_requires,
    package_dir={"": "src"},
    packages=find_packages("src"),
    include_package_data=True,
)

Troubleshooting

ImportError: No module named 'patchcore'

Solution: Make sure PYTHONPATH is set correctly:

export PYTHONPATH=src:$PYTHONPATH

Or run commands from the repository root with the prefix:

env PYTHONPATH=src python bin/run_patchcore.py ...

CUDA out of memory

Solution: Reduce memory usage by:

Using smaller image sizes: --imagesize 192 instead of --imagesize 224
Reducing batch size: --batch_size 1
Using smaller coreset percentage: -p 0.01 instead of -p 0.1
Using CPU FAISS (slower but uses less GPU memory)

FAISS installation issues

Problem: faiss-gpu fails to installSolution: Try installing via conda:

conda install -c pytorch faiss-gpu

Or fall back to CPU version:

pip install faiss-cpu

PyTorch CUDA version mismatch

Problem: PyTorch doesn’t detect your GPUSolution: Install PyTorch matching your CUDA version:

# For CUDA 11.8
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# For CUDA 12.1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Check your CUDA version:

nvcc --version

Permission denied errors

Solution: Don’t run pip with sudo. Use a virtual environment or:

pip install --user -r requirements.txt

Hardware Recommendations

Minimum

GPU: GTX 1080 Ti (11GB)
CPU: 4 cores
RAM: 16GB
Storage: 10GB

Multi-Dataset

GPU: A100 (40GB)
CPU: 16+ cores
RAM: 64GB
Storage: 100GB

Verify GPU Setup

Run this diagnostic script to check your setup:

import torch
import sys

print(f"Python version: {sys.version}")
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    print(f"CUDA version: {torch.version.cuda}")
    print(f"GPU count: {torch.cuda.device_count()}")
    print(f"GPU name: {torch.cuda.get_device_name(0)}")
    print(f"GPU memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.2f} GB")
else:
    print("⚠️  No GPU detected. Training will be slow.")

Next Steps

Quickstart Guide

Train your first model in minutes

Dataset Setup

Prepare the MVTec AD dataset

Configuration

Understand all training parameters

API Reference

Explore the PatchCore API

Get Started

Core Concepts

Training

Inference

Model Zoo

System Requirements

Python Version

GPU Memory

Operating System

CUDA Support

Installation Steps

Optional: Install from setup.py

Troubleshooting

Hardware Recommendations

Minimum

Recommended

Multi-Dataset

Verify GPU Setup

Next Steps

Quickstart Guide

Dataset Setup

Configuration

API Reference

​System Requirements

Python Version

GPU Memory

Operating System

CUDA Support

​Installation Steps

​Optional: Install from setup.py

​Troubleshooting

​Hardware Recommendations

Minimum

Recommended

Multi-Dataset

​Verify GPU Setup

​Next Steps

Quickstart Guide

Dataset Setup

Configuration

API Reference

System Requirements

Installation Steps

Optional: Install from setup.py

Troubleshooting

Hardware Recommendations

Verify GPU Setup

Next Steps