Stable Diffusion 报错 GFPGAN 下载失败无法连接 GitHub 怎么办

Stable Diffusion 启动时报错 GFPGAN 下载失败，通常是因为本地网络无法连接 GitHub 服务器导致依赖安装中断。最推荐的处理方式是手动下载 GFPGAN 源码到本地虚拟环境目录进行安装，或配置 Git 代理后重试。

先说结论：该问题本质是网络连接问题，通过本地离线安装或修正网络配置即可解决。

先确认网络连通性：使用 ping 命令测试 GitHub 域名解析是否正常
先处理依赖安装：手动下载源码至 venv 目录或通过 Git 配置代理
再验证启动日志：观察 webui-user.bat 运行输出是否跳过 GFPGAN 安装步骤

命令速用版

若已配置代理工具，可通过以下 Git 命令设置全局代理后重试安装。

git config `--global` http.https://github.com.proxy http://127.0.0.1:7890
git config `--global` https.https://github.com.proxy http://127.0.0.1:7890

若选择手动安装，进入虚拟环境后使用 pip 安装依赖。

Stable Diffusion 报错 GFPGAN 下载失败无法连接 GitHub 怎么办

cd stable-diffusion-webui\venv\Scripts\GFPGAN
python.exe -m pip install -r requirements.txt
python.exe setup.py develop

为什么会这样

报错的核心原因是 DNS 解析失败或连接超时导致 Git 无法拉取代码。Stable Diffusion WebUI 在首次启动或环境不完整时，会自动尝试从 GitHub 克隆 GFPGAN 仓库，当本地网络无法稳定访问 GitHub 服务器时，pip 安装进程会抛出 RuntimeError 错误。

常见错误日志包含Could not resolve host: github.com或curl 28 Recv failure: Connection was reset，这表明请求在传输层被阻断或域名无法解析为有效 IP 地址。

分步处理

根据网络环境不同，可选择离线手动安装或在线配置代理两种方案。

方案一：手动下载源码安装

适用于无法稳定连接 GitHub 的场景，通过本地文件绕过网络下载环节。

下载源码：在浏览器访问 GitHub 仓库页面，下载 GFPGAN 代码 ZIP 包并解压。
移动文件：将解压后的文件夹重命名为GFPGAN，移动到stable-diffusion-webui\venv\Scripts\目录下。
安装依赖：打开命令提示符，进入该目录，运行python.exe -m pip install -r requirements.txt。
开发模式安装：继续运行python.exe setup.py develop完成注册。

方案二：配置 Git 代理

适用于已有可用代理服务的场景，修复 Git 克隆环节的网络请求。

设置代理：在命令行执行 Git 全局代理配置命令，端口号需根据本地代理软件实际设置调整。
清理缓存：删除stable-diffusion-webui目录下可能存在的临时失败文件。
重试启动：重新运行webui-user.bat，观察是否不再触发 GFPGAN 安装流程。
取消代理：问题解决后，可使用git config `--global` `--unset` http.proxy取消设置。

怎么验证是否生效

安装完成后，需确认 Python 环境能正确导入模块且 WebUI 启动无报错。

命令行验证：在虚拟环境中运行python -c "import gfpgan; print(gfpgan.version)"，若输出版本号则说明库已可用。
启动日志验证：运行 WebUI 启动脚本，日志中不应再出现Installing gfpgan或RuntimeError: Couldn't install gfpgan字样。
功能验证：在 WebUI 界面启用面部修复功能，生成图片时不报错即表示模型调用正常。

常见坑

操作过程中容易因路径错误或环境未激活导致安装无效。

虚拟环境未激活：必须使用venv\Scripts\python.exe而非系统全局 Python，否则库会安装到错误位置。
文件夹层级错误：手动解压时避免产生嵌套文件夹，确保setup.py直接在目标路径下可见。
依赖缺失：若安装 GFPGAN 后报错缺少basicsr或facexlib，需单独 pip 安装这些依赖包。
权限问题：Windows 下若提示权限不足，可尝试以管理员身份运行命令提示符。

常见问题

修改 hosts 文件有用吗？

有用，但 IP 地址可能失效。修改 hosts 文件可强制指定 GitHub 域名对应的 IP 地址，绕过 DNS 污染，但 GitHub 的 IP 会变动，需定期更新。

其他模型下载失败怎么办？

处理方法相同。CLIP、OpenCLIP 等模型安装失败也是因为无法连接 GitHub，可参照 GFPGAN 的手动下载源码到本地目录的方法处理。

更新 pip 能解决这个问题吗？

不能直接解决。pip 版本过低可能导致兼容性问题，但 GFPGAN 下载失败主要是网络连通性问题，更新 pip 后仍需配置网络或手动安装。

参考来源

使用 stable diffusion webui 时，安装 gfpgan 失败的解决方案 (windows 下的操作)
关于最新版 stable-difussion-webui gitclone 下载 gfpgan 等失败
安装 stable-diffusion 时 gfpgan 安装失败
Stable diffusion 本地部署时遇到的问题 (pip 更新、gfpgan、clip 等安装失败)
Windows 系统下解决 Stable Diffusion WebUI 中 GFPGAN 安装失败的问题