ComfyUI ModuleNotFoundError: No module named 'insightface' 修复

如果 ComfyUI 显示 No module named 'insightface'，请修复 ComfyUI 所使用的 Python 环境，而不是系统中随意的某个 Python。

在 Windows 上，直接执行 pip install insightface 通常会失败，因为它会尝试编译原生代码。请使用与你的 Python 版本匹配的预编译 wheel，并仅在人脸工作流确实需要时才添加 ONNX Runtime。

精确错误日志

如果你的终端或启动日志中出现以下任一错误信息，本指南适合你：

ModuleNotFoundError: No module named 'insightface'

症状

ComfyUI 启动时，终端日志中出现以下错误之一：

ModuleNotFoundError: No module named 'insightface'

或：

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

原因

InsightFace 是一个开源的人脸检测与识别库。多个 ComfyUI 人脸相关插件依赖它：

• ReActor（ComfyUI-ReActor）—— 换脸
• IPAdapter FaceID（ComfyUI_IPAdapter_plus）—— 面部特征迁移
• InstantID（ComfyUI-InstantID）—— 保留身份的图像生成
• PuLID —— 面部身份驱动的图像生成

当 InsightFace 缺失时，这些插件中的人脸相关节点可能无法加载，但 ComfyUI 的其余功能通常可以正常运行。

为何在 Windows 上安装尤为困难

PyPI 上发布的 insightface 包是源码发行版。在 Windows 上从源码安装通常需要可用的 C++ 构建工具链、Python 头文件以及兼容的构建依赖。这就是为什么直接执行 pip install insightface 经常因编译错误而失败。

严重程度

中等 —— 仅在你的工作流需要换脸、FaceID、InstantID、PuLID 或其他基于 InsightFace 的功能时才安装。

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

直接运行 pip install insightface 可能产生以下错误之一：

error: Microsoft Visual C++ 14.0 or greater is required.

Building wheel for insightface (pyproject.toml) ... error
ERROR: Failed building wheel for insightface

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

这些错误均指向从源码编译的路径，而非缺少纯 Python 包的简单情况。

解决方案

第一步：使用正确的 Python

安装时请使用启动 ComfyUI 的 Python 环境：

首先检查 Python 版本：

python --version

对于便携包，请使用：

.\python_embeded\python.exe -s --version

第二步：安装匹配的预编译 wheel

在 Windows 上，社区通常使用 ReActor 生态系统提供的预编译 wheel。请根据你的 Python 版本选择对应的 wheel：

对于官方 Windows 便携包，请将 python -m pip 替换为：

.\python_embeded\python.exe -s -m pip

这些是社区 wheel，并非官方 InsightFace PyPI 项目发布的文件。只有在你信任来源时才下载，记录确切 URL 和版本，并优先在已备份的环境中操作。如果你无法判断这个风险，请不要安装该 wheel；改用受支持环境，或查看节点作者记录的依赖路径。

第三步：仅在工作流需要时安装 ONNX Runtime

InsightFace 使用 ONNX Runtime 作为推理后端。通常 CPU 版本的 ONNX Runtime 已经足够：

python -m pip install onnxruntime

如需 NVIDIA GPU 加速：

python -m pip install onnxruntime-gpu

GPU 版 ONNX Runtime 必须与你的 PyTorch 运行时所使用的 CUDA/cuDNN 系列匹配。如果出现 onnxruntime_providers_cuda.dll 错误，请先参阅 ONNX / ONNXRuntime 指南，再修改其他包。

第四步：将 NumPy 降级作为最后手段

不要仅仅因为提到了 InsightFace 就降级 NumPy。当前的 ComfyUI 环境可以合法地使用 NumPy 2.x。

仅当你从所需的人脸插件中看到真实的 NumPy 兼容性错误时，才考虑降级 NumPy。如果必须尝试，请先隔离工作流或进行备份：

python -m pip install "numpy<2"

然后重启 ComfyUI，并仅测试需要该更改的人脸工作流。

第五步：重启 ComfyUI

安装 InsightFace 和 ONNX Runtime 后请重启 ComfyUI。已经导入失败的插件在下次启动之前不会注册其节点。

验证安装

在相同环境中运行以下命令：

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

对于社区 wheel 安装路径，预期输出通常为 0.7.3。

仍然无法解决？

如果错误依然存在，请收集以下信息：

• 完整的 IMPORT FAILED 回溯日志
• python --version 的输出
• python -c "import torch; print(torch.__version__, torch.version.cuda)" 的输出
• 你安装的是 CPU 版还是 GPU 版 ONNX Runtime

参考资料

• ComfyUI 故障排查概览
• ComfyUI 自定义节点故障排查指南
• ComfyUI 模型故障排查指南
• InsightFace GitHub 仓库