IOPaint 图像修复入门教程：从安装、排错到批量去水印-平芜编程栈

IOPaint 图像修复入门教程：从安装、排错到批量去水印

【免费下载链接】IOPaintImage inpainting tool powered by SOTA AI Model. Remove any unwanted object, defect, people from your pictures or erase and replace(powered by stable diffusion) any thing on your pictures.项目地址: https://gitcode.com/GitHub_Trending/io/IOPaint

IOPaint 是一款开源的 AI 图像修复（inpainting）工具，能抹掉照片里多余的人、物体和水印，也可借助扩散模型替换画面内容。本文面向设计师、摄影师和自媒体创作者，带你完成安装、处理常见启动问题，并把工具接入批处理流程。

快速开始：装好并跑通第一张图

在命令行安装主程序，整个过程只需要一条命令：

pip3 install iopaint

装好后，用下面这条命令启动服务。lama是一个轻量修复模型，首次启动时会自动下载，所以耐心等它拉完模型文件：

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

打开浏览器访问http://localhost:8080，上传图片后用画笔涂掉要去除的区域，点击处理。如果结果图中被涂区域被自然填充、周围纹理没有明显断裂，就说明环境已经跑通。CPU 就能运行，只是处理速度慢一些；想更快，先安装对应 CUDA 版本的 PyTorch，再把参数换成--device=cuda：

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

如果你不熟悉命令行，仓库提供了 Windows 一键脚本：先运行scripts/user_scripts/win_setup_cn.bat完成环境配置，之后每次用scripts/user_scripts/win_start_cn.bat启动即可，脚本内部封装了激活虚拟环境和读取配置的步骤，适合不想手动敲命令的新手。

安装或启动失败：先定位，再动手

PyTorch 与 CUDA 版本不匹配

看到CUDNN_STATUS_NOT_INITIALIZED这类报错，通常不是显卡驱动本身的问题，而是 PyTorch 的 CUDA 版本和系统环境对不上。处理办法就是上一节那条cu118安装命令。验证是否修好，可以跑一句自检：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

第二个值输出True即表示 PyTorch 能正常识别 GPU。

显存或内存不够

启动或推理时报内存相关错误时，先降档再谈优化：加--low-mem开启注意力切片和 VAE 分块来省显存；扩散模型吃显存，可以再叠加--cpu-offload把部分计算挪到内存；实在紧张就直接--device=cpu。改完参数重新启动，能进入网页界面并成功处理一张小图，就说明降档生效。

模型下载卡住

模型文件默认会自动下载，网络不稳时容易中断。可以改用iopaint download提前单独下载指定模型，再用iopaint list确认文件是否就位；磁盘空间紧张时，用--model-dir把下载目录指到剩余空间更大的盘符。

提升效率的几个实用参数

加--inbrowser，启动服务时自动打开浏览器标签页，省掉手动输地址的步骤。
涂掩码（mask，即标记"要修复区域"的蒙版）时，开启交互式分割能让 AI 帮你框选物体：iopaint start --enable-interactive-seg，点几下就能得到完整选区，比纯手绘效率高。
处理人像老照片时，加--enable-gfpgan启用人脸修复插件，修复完背景后再把脸部细节补回来，两类问题分开处理，效果更可控。

进阶：把 IOPaint 放进批量工作流

一次只处理一张图很快，但几十张图就要靠命令行批处理。iopaint run命令会读取两个文件夹：原图目录和掩码目录（掩码文件名需与原图一致；如果--mask指向单个文件，则所有图共用这张掩码，正好适合统一去固定位置的水印）：

iopaint run --model=lama --device=cpu \ --image=/path/to/image_folder \ --mask=/path/to/mask_folder \ --output=output_dir

加一个--concat参数，会把原图、掩码和结果拼成一张对比图，方便你逐张验收质量，确认没问题再交付。

如果你有"去水印 + 人脸修复"这类多步需求，思路是拆成两条流水线：先批量跑lama去除水印和划痕，再对含人脸的图单独走带 GFPGAN 插件的流程。视频帧修复同理，用 ffmpeg 抽帧、批处理后再合成回视频即可，核心还是复用上面这条run命令。

检查清单

pip install iopaint无报错，且iopaint list能看到已下载模型
使用 GPU 时，PyTorch 能识别到 CUDA（自检命令输出True）
内存吃紧的项目记得带上--low-mem，扩散模型再加--cpu-offload
批量任务开始前，确认掩码文件名与原图一一对应
启动后浏览器能打开http://localhost:8080并成功处理一张测试图

按这份清单过一遍后，你可以先用lama模型清掉一张图上的水印试手，再逐步尝试交互式分割和 GFPGAN 插件，把 IOPaint 真正嵌进自己的修图流程里。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

IOPaint 图像修复入门教程：从安装、排错到批量去水印