报错 No module named 'insightface'（IPAdapter 人脸加载器 / ReActor 换脸节点不可用）

IPAdapterInsightFaceLoader
No module named 'insightface'

现象与触发场景

常见触发场景：

• 用 ComfyUI Manager 一键安装 IPAdapter_plus / ReActor，Manager 只装了纯 Python 依赖，insightface 编译失败被跳过
• 手动 git clone 了节点仓库但没在 ComfyUI 自带 Python 里跑 requirements.txt
• 按提示 pip install insightface 后，装到了系统 Python 而不是 ComfyUI 的 python_embeded，问题依旧

根因

• insightface 只发布源码包（sdist），安装时必须本地编译 C/C++ 扩展，Windows 上缺 MSVC 编译环境就会失败，所以很多整合包默认不装它
• 节点本身对 insightface 是硬导入（顶层 import），依赖缺失会导致整个节点目录导入失败，其所有人脸节点一起消失
• pip 装到了错误的 Python 解释器，ComfyUI 运行时用的解释器里仍然没有该包

解决步骤

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

1. 先确认你用的到底是哪个 Python
   这是本类问题里最高频的错因：命令装到了系统 Python，ComfyUI 却用自带解释器。便携版解释器在 <ComfyUI根目录>\python_embeded\python.exe，整合包同理；自建 venv 则先激活再装。确认方法：用 ComfyUI 启动日志里的 ** Python executable: 一行核对路径。
   .\python_embeded\python.exe -m pip install insightface
   .\python_embeded\python.exe -c "import insightface; print(insightface.__version__)"
2. 优先让 ComfyUI Manager 走依赖安装流程
   在 Manager 的节点管理里对该节点执行 “Install missing dependencies / 修复”，它会用 ComfyUI 当前解释器执行该节点的 requirements.txt。若日志出现编译失败，进入下一步用预编译轮子。
3. Windows 上直接用社区预编译 whl，绕过编译
   社区为 ComfyUI 场景编译了 cp312（Python 3.12）的 Windows 轮子。务必下载与你的 Python 版本、平台匹配的 whl 文件，再用 ComfyUI 自带解释器本地安装（不建议直接把 URL 交给 pip，避免装到别的解释器或代理失败）。
   :: 下载 insightface-0.7.3-cp312-cp312-win_amd64.whl 后，在所在目录执行：
   ..\..\python_embeded\python.exe -m pip install insightface-0.7.3-cp312-cp312-win_amd64.whl

验证是否修好

补充说明

预编译轮子属于社区第三方产物（多由个人仓库提供），不是官方发布渠道，下载前自行核对文件名中的 cp312/win_amd64 与你的解释器是否一致，cp310 与 cp312 不能混用。若你的 ComfyUI 用 Python 3.10，需要找对应 cp310 的轮子。

来源

1. [65] （节点仓库 issue）　IPAdapterInsightFaceLoader No module named 'insightface' · Issue #770 　https://github.com/cubiq/ComfyUI_IPAdapter_plus/issues/770
2. [66] （社区）　Prebuilt Windows wheel for insightface==0.7.3 (Python 3.12, cp312, amd　https://github.com/skippzz/insightface-0.7.3-cp312-cp312-win_amd64
3. [67] （节点仓库 issue）　i am getting error when try to run install.bat · Issue #154 · Gourieff　https://github.com/Gourieff/ComfyUI-ReActor/issues/154

这条报错要用到的东西

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

同一类别的其他条目

返回报错库