IOPaint 1.6.0 Install: Open Source Inpainting

The #1 mistake with open source inpainting via IOPaint isn’t a bad brush mask. Wrong Python. Or pip sneaks in a CPU-only torch, then --device=cuda quietly does nothing.

IOPaint 1.6.0 hit PyPI on March 18, 2025 – self-hosted erase, inpaint, outpaint. LaMa-class models strip objects; diffusion fills or extends. The GitHub repo (Sanster/IOPaint) went read-only August 13, 2025. So 1.6.0 is the last official line: still installable from PyPI, no fresh upstream fixes coming.

Running archived tooling is a bit like keeping a car the factory no longer supports. It still drives if you bolt on the right parts in the right order – and you stop expecting dealer patches.

System requirements before you touch pip

Package metadata allows Python >=3.7. Real installs land cleanest on 3.10 or 3.11. 3.12 often works. 3.13 is the foot-gun (Pillow pin blows up – more below).

CPU lama is enough for screenshot and photo cleanup. Diffusion on CPU? Possible. Slow enough that most people quit after one try.

Official download source (not random zips)

Use one of these – nothing else:

• Recommended:PyPI package IOPaint 1.6.0 via pip install iopaint
• Docs / flags:iopaint.com/install
• Windows alternative:1-click installer page (Google Drive package + win_setup.bat / win_config.bat / win_start.bat / win_update.bat)

Skip third-party “one-click” mirrors you can’t verify. After the archive, the PyPI wheel is the clean path.

Install IOPaint 1.6.0 step by step

Isolated venv first. Global installs collide with other AI stacks.

# Linux / macOS
python3.11 -m venv iopaint-env
source iopaint-env/bin/activate

# Windows (PowerShell or cmd)
py -3.11 -m venv iopaint-env
iopaint-envScriptsactivate

The catch is GPU order. Install torch before iopaint. Official install docs (as published on iopaint.com/install) pin NVIDIA like this:

pip3 install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu118

AMD on Linux only – same torch versions from the ROCm 5.6 index:

pip3 install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/rocm5.6

CPU-only or Apple Silicon: skip CUDA/ROCm. Plain torch from pip is enough; later start with --device=mps on Apple.

pip3 install iopaint
iopaint start --model=lama --device=cpu --port=8080

Swap to cuda or mps when the stack actually supports it. First launch pulls weights into the default cache (that wait is normal – second run feels different).

First-time configuration (minimum viable)

CLI flags work. Save a config if you restart a lot:

iopaint start-web-config --config-file iopaint-config.json
# save settings in the Gradio UI, then:
iopaint start --config iopaint-config.json

First flags that matter: --model=lama, --device, --port, --model-dir (writable path), optional --inbrowser. Plugins stay opt-in via iopaint start --help – don’t flip every switch on day one.

Think of the first config like packing a day bag, not a shipping container: one erase model, one device, one port. SD can wait.

Verify the install actually works

1. iopaint --version – expect 1.6.0 for the March 2025 PyPI line.
2. Backend check: python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
3. Open http://localhost:8080, drop a small JPEG, brush a mask, run. First inference loads weights; the next pass should feel lighter.

Common install errors and fixes

“Getting requirements to build wheel did not run successfully” / Pillow 9.5.0 – almost always Python 3.13. The package pins Pillow 9.5.0; community reports (GitHub issue #640) show the wheel build dying there. New venv on 3.11. Reinstall.

“CUDA is not available, use cpu instead” – three usual causes. (1) You installed iopaint first and pip gave you CPU torch. (2) Drivers/index mismatch. (3) Hybrid NVIDIA + iGPU laptops: even with torch+cu118, the discrete GPU never gets selected (community thread pattern like the Ryzen iGPU + RTX cases). Fix path: uninstall torch/torchvision, install the cu118 pin above, re-check torch.cuda.is_available(). On multi-GPU boxes, CUDA_VISIBLE_DEVICES still applies.

“iopaint is not recognized” – venv not activated, or the Windows installer path didn’t land on PATH. Activate the env and call the console script again.

“Unrecognized data format” on model load – permissions or a bad write under the default cache. Official FAQ fix: point --model-dir at a folder you own.

Windows installer: localhost / shareable link ValueError – system proxy eating loopback. FAQ recipe: set no_proxy=localhost,127.0.0.1,::1 before the web-config call in win_config.bat.

Black or green SD output – some GPUs hate half precision; try --no-half. OOM: shrink the image, use the UI cropper, or pull flags from the memory guide (--cpu-offload, --cpu-textencoder). Erase models can stay on CPU when VRAM is tight.

Upgrade and uninstall

# Upgrade (pip path)
pip install -U iopaint

# Uninstall package
pip uninstall iopaint

# Windows installer: delete the unzipped folder; win_update.bat / win_config when staying on that path

Default caches (from the FAQ): erase weights under ~/.cache/torch/hub/checkpoints/, diffusion under ~/.cache/huggingface/hub – on Windows, under your user .cache. Other apps share those trees. Delete only IOPaint-related files, or wipe a custom --model-dir you created. Full notes stay on the official FAQ.

Batch without the UI: iopaint run with --image, --mask, and --output once the same env already works interactively.

FAQ

Is open source inpainting with IOPaint still safe to deploy after the archive?

For local 1.6.0 from PyPI, yes. Pin the venv. Skip random forks you haven’t read.

Do I need a GPU for day-one testing?

No. Boot with --model=lama --device=cpu, mask a logo on a laptop photo, confirm the UI path. Example setup: ~8 GB RAM, no dGPU – enough to prove erase works before you chase CUDA or MPS. Move to SD / heavier models only after that path is boringly reliable.

pip says 1.6.0 but GitHub latest release tag looks older – which wins?

PyPI wins. The published wheel is 1.6.0 (March 18, 2025). GitHub tags lagged and stopped moving around the August 13, 2025 archive. After install, iopaint --version is what sits on your PATH. Guides that still say lama-cleaner are stale – the console entry point is iopaint.

Activate the venv. Torch pin first if you have NVIDIA. Then pip3 install iopaint and iopaint start --model=lama --device=cpu --port=8080. Open localhost:8080. Process one test image before plugins or SD.