jonach1998/iopaint repository overview

⁠🎨 IOPaint

A production-ready, batteries-included Docker image for IOPaint⁠. Built for stability, ease of use, and full feature support out-of-the-box. Optimized for NAS and Home Lab environments.

⁠🚀 Why this image?

Unlike the minimal official image, this build is designed to be "Plug & Play" with zero configuration headaches. It solves common issues found in other builds:

• ✅ Full Plugins Pre-Installed: Fixes ModuleNotFoundError for RemoveBG, RealESRGAN, GFPGAN, and RestoreFormer. All dependencies are baked in.
• ✅ NAS Optimized: Includes a LOW_MEM=true flag specifically tuned for Intel Celeron/N-series NAS devices (unloads models to save RAM).
• ✅ Standardized Configuration: Fully configurable via clean Environment Variables (12-Factor App compliant).
• ✅ Self-Healing: Built-in Healthchecks (curl) ensure the container is restarted automatically if it freezes.
• ✅ Drag & Drop Ready: Configured for web-based upload by default (no mandatory input volume binding required).

⁠🛠️ Quick Start (Docker Compose)

Copy this into a compose.yaml file and run docker compose up -d.

name: iopaint
services:
  iopaint:
    image: jonach1998/iopaint:latest
    container_name: iopaint
    hostname: iopaint
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      # CRITICAL: Persistent cache for AI Models.
      # Prevents re-downloading gigabytes of models on every restart.
      - ./iopaint_cache:/app/cache
    environment:
      # --- Hardware Configuration ---
      - DEVICE=cpu             # Options: cpu, cuda, mps
      - MODEL=lama             # Options: lama, mat, zits, mgan, etc.
      
      # --- Performance & NAS Tuning ---
      - LOW_MEM=true           # Set 'true' for NAS/Low-RAM devices. 'false' for max speed.
      
      # --- Feature Toggles (All Enabled by Default) ---
      # Set to 'false' if you want to disable a specific feature.
      # - ENABLE_REMOVE_BG=true
      # - ENABLE_REALESRGAN=true
      # - ENABLE_GFPGAN=true
      # - ENABLE_INTERACTIVE_SEG=true
      
      # --- Intel/CPU Optimizations ---
      - OMP_NUM_THREADS=4
      - MKL_NUM_THREADS=4
    
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 10s
      retries: 3

⁠⚙️ Configuration Reference

You can customize the container using these standard Environment Variables.

⁠Core Settings

⁠Feature Flags (Plugins)

All features are Enabled (true) by default. You can disable them to save startup time or resources.

⁠💾 Volume Persistence

⁠🧩 Troubleshooting / FAQ

I don't see the "Remove Background" button. Wait a few seconds after startup. The first time you use a feature, the container downloads the model. Check logs with docker logs -f iopaint to ensure no download errors occurred.

My NAS is slow when Upscaling. Upscaling (RealESRGAN) is computationally expensive on CPUs. This is normal behavior. Ensure LOW_MEM=true is set to prevent OOM (Out Of Memory) crashes.

Where are the images saved? By default, this image is configured for web usage. When you save an image, it downloads to your computer's browser downloads folder. If you want to save to the NAS, mount a volume to /output and set OUTPUT_DIR=/output.

⁠Credits

• Based on the amazing work by Sanster/IOPaint⁠.
• Packaged, patched, and optimized by jonach1998.