IOPaint 避坑指南：5分钟跑通AI修图，3个报错一次讲清
【免费下载链接】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 图像修复工具，能一键擦掉照片里不想要的物体、水印和路人，也支持用 Stable Diffusion 把某个元素替换成别的东西。本文带你从零装好它，并把新手最常踩的几个坑提前绕过去。
第一条命令：5分钟出第一张修复图
装 IOPaint 其实只需要两行命令。前提是电脑装好了 Python 3.9 及以上版本（命令行输入python --version能出版本号就行）。
pip3 install iopaint iopaint start --model=lama --device=cpu --port=8080第一条把工具装进当前 Python 环境；第二条启动本地服务，默认加载 LaMa 模型（一个擅长"无痕擦除"的轻量模型）。
终端里出现Uvicorn running on http://127.0.0.1:8080后，用浏览器打开这个地址，就能看到修图界面了。第一次启动会自动下载模型，耐心等它走完进度条。
💡 如果你只是日常擦除（去水印、去路人），LaMa 就够用，体积小、CPU 也能跑；只有"把猫换成狗"这类生成任务才需要上扩散模型。
Windows 不想敲命令？用官方一键脚本
项目自带了打包好的 Windows 脚本，位于 scripts/user_scripts/ 目录：
win_setup_cn.bat :: 首次安装（自动配环境、装模型依赖） win_start_cn.bat :: 日常启动双击运行，等脚本跑完、浏览器自动打开即成功。这套脚本内部帮你固定了 PyTorch 版本，省去了很多手动排查的功夫。
装不上？按报错对号入座
pip 下载 torch 极慢或失败
国内网络下载 PyTorch（AI 计算的深度学习框架，相当于 IOPaint 的发动机）很容易超时。解决办法是单独指定国内可访问的 PyTorch 官方索引源：
pip3 install torch==2.1.2 torchvision==0.16.2 \ --extra-index-url https://download.pytorch.org/whl/cu118IOPaint 要求的版本就是 2.1.2，装完再执行pip3 install iopaint，它检测到已有 torch 就不会重复下载。
⚠️ 版本号必须对齐：torch 2.1.2 对应 CUDA 11.8 的预编译包，混用 2.2 或其他版本是后续各种玄学报错的根源。
启动时报 CUDNN_STATUS_NOT_INITIALIZED
这个报错 90% 是 PyTorch 的 CUDA 版本和你显卡驱动不匹配，不是显卡坏了。按上面第一条装 cu118 版本的 torch，然后重启终端再试。
还有一个容易忽略的点：--device=cuda启动后，可以在 IOPaint 页面的设置里核对设备是否真的识别到了 GPU；如果识别失败，先别怀疑代码，检查驱动管理器里显卡状态是否正常。
浏览器打不开 8080 端口
多半是端口被别的软件占了。换个端口即可：
iopaint start --model=lama --device=cpu --port=8081然后访问http://localhost:8081。端口号是任意的，只要不冲突就行。
显存不足、内存爆表？加三个降级参数
你的显存小于 6GB（比如 4GB 的笔记本独显），跑扩散模型时大概率会遇到 OOM（内存溢出，简单说就是显存被模型参数塞满了直接崩掉）。
IOPaint 内置了三个降级开关，直接追加在启动命令里：
iopaint start --model=powerpaint --device=cuda \ --low-mem --cpu-offload --no-half--low-mem：降低推理时的内存峰值--cpu-offload：把暂时不用的模型组件挪到内存，给显存腾地方--no-half：关闭半精度计算，牺牲速度换稳定性
三者可以只开一个，也可以全开。速度会变慢，但能保证不出错。另外模型默认下载位置空间不够时，用--model-dir=/你的目录换个盘存放。
先想清楚：你是要"擦"还是要"画"
选错模型是新手卡住的另一个常见原因，花 10 秒对一下：
| 你的需求 | 用哪个模型 | 特点 |
|---|---|---|
| 去水印、去路人、去杂物 | lama | 快，CPU 可跑 |
| 把图中物体换成别的、扩图 | powerpaint | 生成质量高，吃显存 |
| 老照片划痕修复 | zits | 专为老照片设计 |
模型参数就是--model=后面的名字，随时可以换，不用重装。更多模型清单可以在 IOPaint 的界面里直接切换，也可以看 批量处理模块 了解命令行模式的完整能力。
批量处理老照片，一条命令搞定
照片多的时候不想一张张点，用 IOPaint 的批处理模式：
iopaint run --model=lama --device=cpu \ --image=照片文件夹 --mask=遮罩文件夹 \ --output=输出文件夹--image是原图目录，--mask里放与原图同名、同尺寸的遮罩（白色区域=要修复的区域），结果自动存到--output。如果所有照片要用同一张遮罩，--mask直接指向那个文件即可。
现在就动手试试？
回到终端敲一下第一节的命令，5 分钟后你就能在浏览器里擦掉第一张图里的路人。跑起来之后，如果又蹦出报错，先对照上面三个场景对号入座，大概率能直接解决。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
