ComfyUI 在 Python 3.13 下报 No module named 'insightface' 装不上？手把手完整修复教程

【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI

你在 ComfyUI 里跑人脸相关功能，结果终端弹出 "No module named 'insightface'"？尤其是用 Python 3.13 跑 ComfyUI 嵌入式环境的朋友，90% 都会卡在这一步。别慌，问题不在你电脑，主要是新版本解释器还没轮到 insightface 适配。这篇教程带你按顺序把依赖和主包都装好，再跑两条验证命令确认环境没问题，全程照抄命令就行。

为什么会这样（30 秒看懂）

• insightface 不在 ComfyUI 自带依赖里：它由部分第三方节点按需加载，官方 requirements.txt 中并不包含，缺了它 ComfyUI 本身能启动，但用到就会报 ModuleNotFoundError。相当于公共厨房给了锅，但你想做的菜需要一把专用刀，得自己买。
• Python 3.13 太新，预编译包还没铺满：wheel 是免编译的预打包格式，大多数库发布时只覆盖到 cp311/cp312，pip 找不到 cp313 的 wheel 就会退回源码编译。相当于新系统刚发布，驱动还没适配。
• 源码编译缺工具链必失败：insightface 依赖 onnxruntime，后者构建时要调用 CMake 和 ONNX 编译工具链，缺一个就中断。相当于装修时没带电锤，开工三分钟就停。

动手修复：按这个顺序来

先做这一步，补齐构建工具链。假设你用的是 ComfyUI 嵌入式 Python，命令里的.\python.exe指的就是 ComfyUI 根目录下的 python.exe，如果不是嵌入式环境，把.\python.exe -m换成python -m即可。

第一步：先装 CMake（90% 的人卡在这里）

在 ComfyUI 根目录下打开终端，执行：

.\python.exe -m pip install cmake

看到 Successfully installed 就对了。这条是给后面 onnxruntime 的源码编译补上"电锤"。

第二步：装 ONNX 运行时，别急着装主包

.\python.exe -m pip install onnxruntime

如果报 CMake 错误或者提示找不到可用 wheel，执行这条：

.\python.exe -m pip install onnx-weekly

onnx-weekly 是 ONNX 运行时的预发布渠道，对新版本 Python 的 cp313 轮子铺得更全。看到 Successfully installed 说明这一步过了。

第三步：补齐其余 Python 依赖

跑完这条，下一步处理剩下的配套库——这些都是纯 Python 或带通用 wheel 的包，装起来很稳：

.\python.exe -m pip install albumentations cython easydict onnx prettytable scikit-learn

第四步：最后才装 insightface 主包

依赖都齐了，再装主包。这一步用针对 Python 3.13 预编译的 wheel 包（从固定镜像源获取，不依赖源码编译），安装命令由你使用的社区资源页提供，格式形如：

.\python.exe -m pip install insightface==0.7.3

⚠️ 顺序别颠倒：先跑完前三步再装主包，否则 pip 会卡在编译环节反复报错。

装好了吗？跑这两条验证

在同一个终端里依次执行：

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

两条都正常输出版本号（如 0.7.3、1.20.0），✅ 说明 insightface 与 ONNX 运行时都已就位。

如果第一条报 "No module named 'insightface'"，说明包装到了别的解释器里——检查一下.\python.exe -m pip --version显示的 python 路径是不是你以为的那个，不是的话把安装命令里的解释器路径改回 ComfyUI 的。如果第一条报 onnxruntime 相关错误，❌ 回到第二步换用 onnx-weekly 重装。

踩坑速查（你可能还会碰到这几种）

Q：pip 报权限不足（Permission denied / access is denied）怎么办？

在命令末尾加--user参数，装到用户目录即可。Linux/Mac 上不建议乱加 sudo，容易把系统 Python 和嵌入式 Python 的依赖装混。

Q：我是 Linux 或 Mac，能直接照抄吗？

不行。教程中的 wheel 是win_amd64的 Windows 预编译包，Linux/Mac 请去对应渠道找 cp313 的预编译轮子；实在没有，先确认装好 cmake 和 onnx 相关工具链再尝试源码编译。

Q：Python 3.12 环境也要这样折腾吗？

不用。3.12 生态的 wheel 铺得比较全，直接pip install insightface大概率能装上。本文流程主要是给 3.13 的"新系统"准备的。

Q：装了之后启动 ComfyUI 还是报同样错误？

九成是装了 ComfyUI 自带 python 之外的另一个解释器。用.\python.exe -m pip list | findstr insightface确认包在这个环境里，不在就换回正确路径重装一遍。

装好后回到 ComfyUI 重新启动，之前报错的工作流应该就能正常跑通。如果还有报错，把完整日志贴出来看看，大概率秒定位。

【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.项目地址: https://gitcode.com/GitHub_Trending/co/ComfyUI