insightface 在 Windows 上编译失败（Building wheel for insightface finished with status 'error'）

Building wheel for insightface (pyproject.toml): finished with status 'error'

现象与触发场景

常见触发场景：

• Windows 便携版 / 秋叶整合包，直接 pip install insightface 触发源码编译
• Python 版本过高（如 3.12）导致旧版预编译 wheel 不可用
• 缺少 Visual Studio C++ 生成工具，编译 Cython 扩展失败

根因

• PyPI 上的 insightface 只有源码包，安装时会现场编译 Cython/C++ 扩展；Windows 上没有 MSVC 生成工具时编译直接失败
• 社区流传的预编译 wheel 是按 Python 版本命名的（例如 insightface-0.7.3-cp310-cp310-win_amd64.whl 对应 Python 3.10、cp311 对应 3.11），Python 版本对不上就无法安装该 wheel，只能退回源码编译然后失败
• ComfyUI 用的是便携版内置解释器，wheel 必须装进这个解释器；同时一定要用该解释器自己的 pip，混用系统 pip 会出现「装成功了但还报没有模块」

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

1. 先确认便携版 Python 版本，再选对应 cpXXX 的预编译 wheel（首选方案）
   不要直接源码编译。先查便携版解释器版本（决定用 cp310 还是 cp311 等 wheel），然后下载社区提供的 insightface 预编译 wheel 安装。这是 ReActor 作者在 README 中给出的官方建议做法，也是折腾最少的路子：用便携版解释器自己的 pip 安装本地 wheel 文件。wheel 文件与命令必须指向同一个解释器。
   ..\..\python_embeded\python.exe --version
   ..\..\python_embeded\python.exe -m pip install insightface-0.7.3-cp310-cp310-win_amd64.whl
2. 没有匹配 wheel 时，安装 MSVC 生成工具让它能编译
   若必须源码编译，就装 Visual Studio Build Tools（含「使用 C++ 的桌面开发」工作负载），装完重开命令行窗口再 pip install insightface。报错里出现 'Microsoft Visual C++ 14.0 or greater is required' 就是这个原因。编译过程会持续数分钟且需要联网拉取依赖，属正常现象。
   ..\..\python_embeded\python.exe -m pip install insightface
3. 补装 insightface 运行所需的 onnxruntime 与 facexlib
   换脸系节点除了 insightface 还需要 onnxruntime（有 GPU 时用 onnxruntime-gpu）以及 facexlib。注意 onnxruntime 与 onnxruntime-gpu 不要同时装，否则 CUDA provider 加载会混乱；GPU 版要与本机 CUDA/cuDNN 版本匹配，不匹配时典型表现是 Failed to create CUDAExecutionProvider 或 LoadLibrary failed with error 126。
   ..\..\python_embeded\python.exe -m pip install onnxruntime-gpu
   ..\..\python_embeded\python.exe -m pip install facexlib
4. 在便携版解释器里验证安装结果
   安装完不要只看 pip 的 Successfully installed，要在便携版解释器里真正 import 一次。换脸节点还依赖模型文件（如 inswapper_128.onnx、buffalo_l 人脸模型），模型缺失会报另一类错误，安装成功后仍需核对模型目录。
   ..\..\python_embeded\python.exe -c "import insightface; print(insightface.__version__)"
   ..\..\python_embeded\python.exe -c "import onnxruntime; print(onnxruntime.get_available_providers())"

验证是否修好

补充说明

error_text 取自 deepinsight/insightface issue #2696 标题原文（标题即 'Building wheel for insightface (pyproject.toml): finished with status \'error\''）。insightface-0.7.3-cp310-cp310-win_amd64.whl 这一 wheel 命名与安装写法来自 ReActor README 的 Windows 说明原文。triton/sageattention 类包的 Windows 适配版本较多，此条不涉及。

来源

1. [83] （节点仓库 issue）　Building wheel for insightface (pyproject.toml): finished with status 　https://github.com/deepinsight/insightface/issues/2696
2. [240] （节点仓库 issue）　installing requirements says "Failed building wheel for insightface"　https://github.com/hacksider/Deep-Live-Cam/issues/1578
3. [241] （社区）　How to fix this issue "ERROR: Failed building wheel for insightface"　https://stackoverflow.com/questions/76739044/how-to-fix-this-issue-error-failed-building-wheel-for-insightface
4. [242] （社区）　Installation and Setup | Gourieff/ComfyUI-ReActor　https://deepwiki.com/Gourieff/ComfyUI-ReActor/2-installation-and-setup

这条报错要用到的东西

按本条报错所属的类别（热门自定义节点/工作流专有报错）列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

同一类别的其他条目

返回报错库