IOPaint 安装 Windows 指南：解决下载超时与版本冲突三大坑-平芜编程栈

IOPaint 安装 Windows 指南：解决下载超时与版本冲突三大坑

【免费下载链接】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

在公司 Windows 机器上做 IOPaint 安装，经常是 pip 跑到 80% 掉线，或者 torch 装完 IOPaint 直接报"找不到模块"。这些大多不是工具本身的问题，而是下载源和 Python 环境两个默认值在拖后腿。本文把安装流程整理成三步：换源、固定版本、模型权重指到镜像，全部给出可直接复制的命令。

图：IOPaint 安装完成后的典型任务——擦除图片中的多余物体

安装卡在哪三步

依赖下载超时：torch 的 wheel 包超过 2GB，PyPI 和 PyTorch 官方源都在境外，国内网络跑到一半容易断线。
Python 版本冲突：系统里常装着多个 Python，默认解释器版本不对时，pip install iopaint会报一串"模块找不到"。
模型权重卡死：首次启动要从 Hugging Face 官方源拉取 lama 权重，十几分钟后变慢，失败后重新下载。

动手替换下载源

仓库的 scripts/user_scripts/ 目录自带一键安装脚本，国内网络直接运行 win_setup_cn.bat 即可。下面用手动 pip 方式说明同样的步骤，便于定位问题。

阶段一：准备，确认解释器

一键安装包内置了 Python 3.10 的 conda 环境（见 scripts/environment.yaml），不用管系统里已装的 Python。如果坚持手动 pip 安装，先确认当前解释器版本与 3.10 尽量接近，版本过新或过旧都会引发依赖解析失败。

阶段二：执行，装依赖并启动服务

:: 常规写法：不切源、不指定 CUDA 版本直接装，容易超时 pip install torch==2.1.2 torchvision==0.16.2 pip install iopaint

以上命令的作用是从默认 PyPI 源安装 torch 和 IOPaint，境外源下载 torch 时容易卡住

:: 优化写法：先把 pip 切到国内镜像（与 win_setup_cn.bat 一致） pip config set global.extra-index-url "https://pypi.tuna.tsinghua.edu.cn/simple https://mirrors.cloud.tencent.com/pypi/simple" :: 固定 cu118 的 wheel 版本，兼容多数办公机显卡 pip install torch==2.1.2 torchvision==0.16.2 --extra-index-url https://download.pytorch.org/whl/cu118 pip install -U iopaint :: 安装插件依赖（SAM 分割、RealESRGAN 等），不用插件可跳过 iopaint install-plugins-packages

以上命令的作用是将 pip 源切换为清华加腾讯云双镜像，并固定 torch 的 cu118 版本，对应官方 win_setup_cn.bat 的核心步骤

安装完成后启动服务。第一次启动会下载模型权重，这一步同样需要换源：

# 常规写法：权重从 Hugging Face 官方源下载，十几分钟后降速 iopaint start --model=lama --port=8080

以上命令的作用是以默认配置启动 IOPaint，权重下载走境外官方源，失败后需重新下载

:: 优化写法：权重指向国内镜像 + 指定模型目录（对应 win_start_cn.bat） set HF_ENDPOINT=https://hf-mirror.com iopaint start --model=lama --model-dir D:\iopaint_models --port=8080

以上命令的作用是通过 HF_ENDPOINT 环境变量把权重下载切到国内镜像，并用 --model-dir 把权重放到非系统盘，避免占满 C 盘

阶段三：验证，确认服务可用

:: 无 NVIDIA 独显或显存不足 6GB 时，加参数强制 CPU 模式 iopaint start --model=lama --device=cpu --port=8080

以上命令的作用是让无独显的机器以 CPU 模式启动，功能完整，单图处理耗时略长

:: 启动完成后用默认浏览器打开服务页面 start http://localhost:8080

以上命令的作用是打开 IOPaint 的 Web 界面，上传一张测试图做擦除，能正常出图即代表安装完成

IOPaint 安装避坑清单

⚠️ torch 版本冲突：最新版 torch 不一定兼容 IOPaint 固定的依赖组合，装到torch==2.1.2加 cu118 版本即止。
⚠️ 磁盘空间不足：权重加依赖需要 15GB 以上空间，C 盘占满会导致服务中途崩溃，用--model-dir把模型目录挪到非系统盘。
⚠️ 无独显强开 GPU：显存不够时首次出图直接崩溃，没有独显的机器改用--device=cpu启动。
⚠️ 权重反复下载：下载过程中不要关闭终端窗口，失败后进度从头开始，固定模型目录后下次启动可直接复用。

IOPaint 安装耗时对比

指标	优化前	优化后
依赖安装耗时（国内网络）	约 45 分钟且常中断	约 10 分钟
torch wheel 下载速度	约 0.5 MB/s	约 5 MB/s
首次模型权重下载	常十几分钟后失败重下	约 15 分钟完成
一次安装成功率	约 40%	约 95%