Installation

Complete installation guide for Image Matching WebUI

Installation

Requirements

• Python 3.10+

Just getting started? Try the quick start guide for the simplest setup.

Installation Methods

PyPI (Recommended)

For most users, PyPI is the fastest and easiest way:

pip install imcui

With Dataset Support

Include automatic dataset downloading:

pip install imcui[datasets]

System Requirements

Windows, macOS, or Linux with Python 3.10+

GPU Support

CUDA 11.8+ for GPU acceleration (optional)

Docker

Use Docker for isolated, reproducible environments:

docker pull vincentqin/image-matching-webui:latest
docker-compose up webui

Background Mode

docker-compose up -d webui

Custom Port

docker run -p 8080:7860 vincentqin/image-matching-webui:latest

Source Installation

Install from the GitHub repository for development or latest features:

git clone https://github.com/Vincentqyw/image-matching-webui.git
cd image-matching-webui
pip install -e .

This installs in editable mode, allowing you to make changes to the source code without reinstalling.

Environment Setup

Virtual Environment (Recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install imcui

GPU Configuration

For CUDA-enabled systems:

# Check CUDA availability
python -c "import torch; print(torch.cuda.is_available())"

# Set specific GPU (optional)
export CUDA_VISIBLE_DEVICES=0

Data Management

Example Datasets

Example datasets (82MB) automatically download on first run:

Linux/macOS

~/.cache/imcui/datasets/

Windows

%LOCALAPPDATA%\imcui\datasets\

Custom Data Paths

Set a custom location for example datasets:

Environment Variable

export IMCUI_DATA_DIR=/path/to/datasets

CLI Flag

imcui -d /path/to/datasets

Configuration File

example_data_root: /path/to/datasets

Verification

Test your installation:

# Check version
imcui --version

# Display available options
imcui --help

Expected output shows version 1.0.0 and CLI options.

Troubleshooting

Import Errors

Ensure you’re using the correct Python environment and all dependencies are installed:

pip install --upgrade imcui

CUDA Not Found

Verify CUDA installation:

nvidia-smi

For CPU-only usage, the application will automatically fallback.

Permission Denied

Use a virtual environment or user installation:

pip install --user imcui

Still having issues? Check our troubleshooting guide for common problems and solutions.