ComfyUI 缺少 InsightFace 模块

症状

ComfyUI 启动时，终端日志中出现：

ModuleNotFoundError: No module named 'insightface'

或者：

Cannot import ... module for custom nodes: No module named 'insightface'

原因

InsightFace 是一个开源的人脸检测与识别库，由 deepinsight 团队开发。以下 ComfyUI 插件依赖它：

• ReActor (ComfyUI-ReActor) — 换脸
• IPAdapter FaceID (ComfyUI_IPAdapter_plus) — 面部特征迁移
• InstantID (ComfyUI-InstantID) — 身份保持生成
• PuLID — 面部身份驱动生成

缺少 InsightFace 时，上述插件中所有涉及人脸的节点将无法使用，但 ComfyUI 的其他功能不受影响。

为什么在 Windows 上特别难装

InsightFace 的 Python 包（insightface）包含 Cython 扩展代码，安装时需要在本地编译 C++ 源码。PyPI 上没有提供 Windows 的预编译 wheel，因此 pip install insightface 在 Windows 上几乎必然失败，除非你的系统已经安装了完整的 C++ 编译工具链。

严重程度

中 — 如果你需要使用换脸或人脸相关的工作流，必须安装。

安装失败时常见的报错信息

直接运行 pip install insightface 时，你可能会看到以下错误之一：

error: Microsoft Visual C++ 14.0 or greater is required.
Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/

Building wheel for insightface (pyproject.toml) ... error
error: subprocess-exited-with-error

fatal error C1083: Cannot open include file: 'Python.h': No such file or directory

ERROR: Failed building wheel for insightface
ERROR: Could not build wheels for insightface, which is required to install pyproject.toml-based projects

这些错误都指向同一个根本原因：缺少 C++ 编译环境。下面的解决方法可以绕过编译步骤。

解决方法

方法一：使用预编译 wheel 安装（推荐）

这是最简单可靠的方式，直接安装已编译好的 .whl 文件，无需任何编译工具。

第 1 步：确认你的 Python 版本

在 Wonderful Launcher 的「环境」页面中打开终端（Terminal），输入：

python --version

记住输出的版本号（如 3.10.x、3.11.x、3.12.x 或 3.13.x）。

第 2 步：安装对应版本的预编译 wheel

根据你的 Python 版本，在终端中执行对应的命令：

Python 3.10：

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp310-cp310-win_amd64.whl

Python 3.11：

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp311-cp311-win_amd64.whl

Python 3.12：

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp312-cp312-win_amd64.whl

Python 3.13：

pip install https://github.com/Gourieff/Assets/raw/main/Insightface/insightface-0.7.3-cp313-cp313-win_amd64.whl

第 3 步：安装 onnxruntime

InsightFace 需要 onnxruntime 作为推理后端。如果你还没有安装，需要执行：

如果你有 NVIDIA 显卡（推荐）：

pip install onnxruntime-gpu

如果你没有独立显卡或使用 AMD 显卡：

pip install onnxruntime

第 4 步：处理可能的 NumPy 版本冲突

InsightFace 0.7.3 与 NumPy 2.x 不兼容。如果安装后运行时出现 NumPy 相关错误（如 AttributeError: module 'numpy' has no attribute 'int'），需要降级 NumPy：

pip install "numpy<2"

第 5 步：重启 ComfyUI

安装完成后，重启 ComfyUI 使更改生效。

方法二：安装 Visual C++ Build Tools 后从源码编译

如果预编译 wheel 不适用于你的环境（例如 Python 版本没有对应的 wheel），可以安装编译工具后从源码构建。

1. 下载并安装 Microsoft C++ Build Tools
2. 在安装程序中，勾选「使用 C++ 的桌面开发」(Desktop development with C++) 工作负载
3. 安装完成后重启电脑
4. 在 Wonderful Launcher 终端中执行：

   pip install cython
   pip install insightface

验证安装是否成功

在终端中输入以下命令，如果没有报错则说明安装成功：

python -c "import insightface; print(insightface.__version__)"

正常输出应为：0.7.3

仍然无法解决？

如果以上方法都无法解决问题，请通过应用内的「联系我们」按钮联系技术支持，并附上终端中的完整报错信息。