IntermediateIOPaintAIImage InpaintingPythonPyTorchStable DiffusionDeep LearningComputer VisionGradioFastAPI

IOPaint: AI-Powered Image Inpainting Tool Setup

Complete setup guide for IOPaint - a free and open-source image inpainting and outpainting tool powered by state-of-the-art AI models. Remove unwanted objects, defects, and people from images or replace them using stable diffusion. Supports CPU, GPU, and Apple Silicon with various AI models including LaMa, PowerPaint, and AnyText.

Step 1
System Prerequisites
IOPaint is a Python-based AI tool that runs on macOS, Linux, and Windows. It supports CPU, GPU (CUDA), and Apple Silicon (MPS) acceleration. For GPU acceleration, you need NVIDIA drivers (Windows/Linux) or Metal framework (macOS). Minimum 4GB RAM recommended, 8GB+ preferred for larger models. You'll need Python 3.8+ and pip package manager.
```
# Check Python version
python3 --version  # Should be 3.8+

# Check pip version
pip3 --version

# Check your OS
uname -a  # Linux/macOS
systeminfo | findstr /B /C:"OS Name"  # Windows

# For GPU acceleration, check CUDA
nvidia-smi  # Shows GPU and CUDA version (Windows/Linux)
```
⚠ Heads up: The repository was archived on August 13, 2025, and is now read-only. Consider using a fork or alternative active projects for future updates.

Step 2

Installation via pip (Recommended)

The simplest way to install IOPaint is through pip. This installs the Python package and CLI tool. After installation, you can start the web UI immediately. Models will download automatically on first run.

# Install IOPaint
pip3 install iopaint

# Start with LaMa model (object erasing) on CPU
iopaint start --model=lama --device=cpu --port=8080

# For GPU acceleration (NVIDIA CUDA)
pip3 install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu118
iopaint start --model=powerpaint --device=cuda --port=8080

# For AMD GPU (Linux only with ROCm)
pip3 install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/rocm5.6
iopaint start --model=lama --device=mps --port=8080

# Verify installation
iopaint --version

Step 3
Installation via Source (Development)
Clone the repository for development or to use the latest version. This method requires Node.js for the frontend and gives you access to the full codebase. You'll need to build the frontend assets and install Python dependencies.
```
# Clone the repository
git clone https://github.com/Sanster/IOPaint.git
cd IOPaint

# Install backend dependencies
pip3 install -r requirements.txt

# Build frontend (requires Node.js 18+)
cd web_app
npm install
npm run build
cp -r dist/ ../iopaint/web_app

# Start backend service
cd ..
python3 iopaint/main.py start --model=lama --port=8080

# Or for development mode (hot-reload)
cd web_app
VITE_BACKEND=http://127.0.0.1:8080 npm run dev
```
⚠ Heads up: The web_app directory contains the Gradio frontend. For production use, build it once with 'npm run build'. For development, use 'npm run dev' for hot-reloading.

Step 4

Available AI Models

IOPaint supports multiple AI models for different tasks. Erase models remove unwanted elements, while diffusion models (Stable Diffusion-based) can replace or outpaint content. Some models require larger VRAM.

# LaMa - Erase model (fast, lightweight)
iopaint start --model=lama --device=cpu

# PowerPaint - Replace objects with inpainting
iopaint start --model=powerpaint --device=cuda

# PowerPaint V2 - Improved version
iopaint start --model=powerpaint_v2 --device=cuda

# AnyText - Add text to images
iopaint start --model=anytext --device=cuda

# BrushNet - Precise inpainting with brush strokes
iopaint start --model=brushnet --device=cuda

# SDXL - High-quality inpainting
iopaint start --model=sd_xl --device=cuda

# List all available models
iopaint start --help

⚠ Heads up: Diffusion models (powerpaint, anytext, brushnet, sd_xl) require more VRAM. LaMa works well on CPU with 4GB+ RAM. SDXL models need 8GB+ GPU memory for good performance.

Step 5

Using Plugins

IOPaint has several plugins for enhanced functionality: Segment Anything for interactive object segmentation, RemoveBG for background removal, RealESRGAN for super-resolution, and face restoration models (GFPGAN, RestoreFormer). Enable them during startup.

# Enable Interactive Object Segmentation (Segment Anything)
iopaint start --enable-interactive-seg --interactive-seg-device=cuda

# Enable all plugins
iopaint start --enable-interactive-seg --enable-rembg --enable-anime-seg --enable-fs --enable-res --device=cuda

# Plugin options:
# --enable-interactive-seg : Segment Anything plugin
# --enable-rembg : Remove background plugin
# --enable-anime-seg : Anime segmentation
# --enable-fs : Face restoration (GFPGAN/RestoreFormer)
# --enable-res : RealESRGAN super-resolution

# Each plugin can have separate device setting
iopaint start --enable-interactive-seg --interactive-seg-device=cuda --model=lama --device=cpu

Step 6

Configure Model Directory

By default, models download to the user cache directory. You can customize this location, especially useful for shared systems or limited disk space scenarios. Models are cached and reused across sessions.

# Default model cache location:
# Linux: ~/.cache/iopaint/
# macOS: ~/Library/Caches/iopaint/
# Windows: %LOCALAPPDATA%\iopaint\models

# Set custom model directory
iopaint start --model=lama --device=cpu --model-dir=/path/to/models

# Or set environment variable
export XDG_CACHE_HOME=/custom/cache/path
iopaint start --model=lama

# Check model directory
iopaint start --model=lama --device=cpu --show-dir

Step 7
Using the Web Interface
Once IOPaint is running, open your browser at http://localhost:8080. The interface allows you to upload images, create masks, and apply AI models. The Gradio UI is intuitive - click on the image to draw masks, select models, and adjust parameters.
```
# Start IOPaint
iopaint start --model=lama --device=cpu --port=8080

# Then open in browser:
# http://localhost:8080

# UI workflow:
# 1. Upload an image or drag-and-drop
# 2. Select a brush tool to mask areas
# 3. Adjust brush size for precision
# 4. Click 'Erase' or 'Inpaint'
# 5. Download the result

# For remote access
iopaint start --model=lama --device=cuda --port=8080 --host=0.0.0.0
```
⚠ Heads up: By default, IOPaint binds to localhost. To access from other devices on your network, add --host=0.0.0.0. Use with caution as this exposes your service.

Step 8

Batch Processing Images

Process multiple images via CLI for automation. You need corresponding mask images for each input image. The batch mode is ideal for programmatic workflows or processing large numbers of images.

# Batch process images from folders
iopaint run --model=lama --device=cpu \
  --image=/path/to/image_folder \
  --mask=/path/to/mask_folder \
  --output=/path/to/output_dir

# Use single mask for all images
iopaint run --model=lama --device=cpu \
  --image=/path/to/images \
  --mask=/path/to/single_mask.png \
  --output=/path/to/output

# Batch options:
# --image : Input image folder or single image
# --mask : Mask folder (corresponding names) or single mask file
# --output : Output directory for results
# --device : cpu, cuda, or mps

Step 9

Fine-tune Configuration

Advanced users can customize behavior through environment variables. Control cache locations, memory limits, and model loading behavior for optimal performance on your system.

# Set custom cache directory
export XDG_CACHE_HOME=/path/to/cache

# Allow MPS fallback on macOS
export PYTORCH_ENABLE_MPS_FALLBACK=1

# Limit cache to reduce memory
export ONEDNN_PRIMITIVE_CACHE_CAPACITY=1
export LRU_CACHE_CAPACITY=1
export TORCH_CUDNN_V8_API_LRU_CACHE_LIMIT=1

# Custom model loading directory
export MODEL_DIR=/path/to/models

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export XDG_CACHE_HOME=/custom/cache' >> ~/.bashrc

Step 10

Using Local Stable Diffusion Checkpoints

IOPaint supports loading custom Stable Diffusion checkpoints (.ckpt or .safetensors files) for personalized inpainting. Place your models in the correct directory and specify them when starting.

# Place your .ckpt or .safetensors in:
# ~/.cache/iopaint/models/diffusion/custom/

# Start with custom model via path
# (use --model-dir to set custom checkpoint location)

# Supported custom models:
# - Any Stable Diffusion inpainting checkpoint
# - Safety: Use trusted sources only
# - File formats: .ckpt, .safetensors (recommended)

Step 11

Troubleshooting Common Issues

Solutions to frequent problems: Out of memory errors, slow performance, model download failures, and GPU compatibility issues.

# Out of memory on GPU
# - Switch to CPU: iopaint start --device=cpu
# - Use smaller model: Use lama instead of sd_xl
# - Reduce batch size in UI

# Slow CPU performance
# - Use laMa model (lightweight)
# - Close other applications
# - Consider upgrading RAM

# Model download failed
# - Check internet connection
# - Set custom download mirror
# - Download manually from Hugging Face

# CUDA errors
# - Verify NVIDIA drivers: nvidia-smi
# - Check CUDA version compatibility
# - Try CPU fallback: --device=cpu

# Windows GPU issues
# - Install PyTorch with CUDA: pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
# - Ensure no conflicting DLLs

# macOS Metal (MPS) issues
# - Update to latest macOS
# - Set PYTORCH_ENABLE_MPS_FALLBACK=1

# Port in use
iopaint start --model=lama --port=8081  # Use different port

⚠ Heads up: If you encounter import errors, ensure all dependencies are installed: pip install -r requirements.txt. For Windows GPU support, use the appropriate PyTorch build with CUDA.

Step 12

Performance Tips

Optimize IOPaint for your hardware. GPU acceleration dramatically improves processing times. Choose appropriate models based on your hardware capabilities and task requirements.

# GPU vs CPU comparison:
# LaMa on CPU: 5-30 seconds per image
# LaMa on GPU: 1-5 seconds per image
# PowerPaint on CPU: 30-120 seconds per image
# PowerPaint on GPU: 5-30 seconds per image

# Best practices:

# 1. Use GPU when available
iopaint start --device=cuda  # NVIDIA
iopaint start --device=mps   # Apple Silicon

# 2. Choose model based on task:
# - Erase objects: LaMa (fast)
# - Replace with context: PowerPaint
# - Add text: AnyText
# - High quality: SDXL (needs VRAM)

# 3. Keep models cached for reuse
# 4. Close other GPU applications
# 5. Use batch processing for multiple images

IOPaint: AI-Powered Image Inpainting Tool Setup

System Prerequisites

Installation via pip (Recommended)

Installation via Source (Development)