ComfyUI 提示 No module named 'insightface'：Windows 修復方法

如果 ComfyUI 日誌裡出現 No module named 'insightface'，重點是修復 ComfyUI 實際使用的那個 Python 環境，不是隨便找一個系統 Python 去裝包。

在 Windows 上，直接執行 pip install insightface 經常會失敗，因為它往往會走本地編譯流程。更穩的做法是安裝和 Python 版本匹配的預編譯 wheel；只有當你的臉部工作流真的需要時，再補 onnxruntime。

典型症狀

ComfyUI 啟動時，日誌裡會出現類似報錯：

ModuleNotFoundError: No module named 'insightface'

或者：

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

原因

InsightFace 是人臉檢測和識別庫。很多和換臉、人臉特徵保持相關的 ComfyUI 插件會依賴它，例如：

• ReActor：換臉
• IPAdapter FaceID：保留人臉特徵
• InstantID：身份一致的人像生成
• PuLID：基於身份特徵驅動生成

少了 InsightFace 時，相關節點可能加載失敗，但 ComfyUI 其他不依賴人臉分析的部分仍然可能繼續工作。

為什麼 Windows 上特別容易裝壞

PyPI 上的 insightface 經常以源碼分發形式出現。Windows 本地編譯需要：

• 可用的 C++ 構建工具鏈
• Python 頭文件
• 兼容的構建依賴

所以很多人看到的並不是“缺包”，而是“編譯失敗”。

嚴重程度

中等。 只有當你的工作流確實依賴 ReActor、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 包缺失的問題。

解決方法

第 1 步：先用對 Python

必須安裝到 真正啟動 ComfyUI 的那個 Python 環境 裡：

先檢查 Python 版本：

python --version

portable 包則執行：

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

第 2 步：安裝和版本匹配的預編譯 wheel

在 Windows 上，社區裡最常用的是 ReActor 生態提供的預編譯 wheel。按你的 Python 版本選擇：

如果你用的是官方 Windows portable 包，把 python -m pip 換成：

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

這些 wheel 不是官方 InsightFace PyPI 專案發布的文件，而是社群常用分發路徑。只有在你信任來源時才下載，記錄精確 URL 和版本，並優先在已備份的環境裡操作。如果你無法判斷這個風險，請不要安裝該 wheel；改用受支援環境，或查看節點作者記錄的相依性路徑。

第 3 步：只有在需要時再裝 ONNX Runtime

InsightFace 的推理通常依賴 ONNX Runtime。很多場景下 CPU 版已經夠用：

python -m pip install onnxruntime

如果你明確需要 NVIDIA GPU 加速：

python -m pip install onnxruntime-gpu

但 onnxruntime-gpu 必須和你的 CUDA / cuDNN 棧匹配。如果報 onnxruntime_providers_cuda.dll 之類錯誤，不要繼續亂改包，先看 ONNX / ONNX Runtime 指南。

第 4 步：把 NumPy 降級當成最後手段

不要因為報錯裡提到 InsightFace，就先手降級 NumPy。 現在很多 ComfyUI 環境本來就能正常使用 NumPy 2.x。

只有當你看到 明確的 NumPy 兼容報錯，而且確定來自你正在用的人臉插件時，才考慮先備份環境再試：

python -m pip install "numpy<2"

然後只測試那個需要它的人臉工作流。

第 5 步：重啟 ComfyUI

InsightFace 或 ONNX Runtime 裝好之後，必須重啟 ComfyUI。 已經導入失敗過的插件，不會在當前會話裡自動重新註冊節點。

如何驗證

在 同一個環境 裡執行：

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

社區 wheel 常見輸出是 0.7.3。

還不行？

如果問題還在，至少收集這些信息：

• 完整的 IMPORT FAILED traceback
• python --version 輸出
• python -c "import torch; print(torch.__version__, torch.version.cuda)" 輸出
• 你安裝的是 CPU 版還是 GPU 版 ONNX Runtime

如果你想走更快的恢復路徑，先用 Wonderful Launcher 檢查當前環境、任務日誌和依賴狀態；需要人工協助時再走支持渠道。

參考來源

• ComfyUI 官方排障總覽
• ComfyUI 自定義節點排障
• ComfyUI 模型問題排障
• InsightFace GitHub repository