ComfyUI ModuleNotFoundError: No module named 'insightface' の修復

ComfyUI に No module named 'insightface' というエラーが表示された場合、システム全体の Python ではなく、ComfyUI が実際に使用している Python 環境にインストールを行う必要があります。

Windows 環境において、通常の pip install insightface は C++ コンパイルが必要になるため高確率で失敗します。使用している 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 は、オープンソースの顔検出・顔認識ライブラリです。複数の顔関連カスタムノードがこれに依存しています：

• ReActor（ComfyUI-ReActor）—— 顔交換
• IPAdapter FaceID（ComfyUI_IPAdapter_plus）—— 顔特徴の転送
• InstantID（ComfyUI-InstantID）—— ID 保持画像生成
• PuLID —— ID 駆動型画像生成

InsightFace が欠如していると、これらのノードはロードされませんが、ComfyUI の他の基本機能は問題なく動作します。

Windows 上でのビルド失敗について

PyPI に登録されている標準の insightface パッケージはソースコード配布形式です。Windows でこれをソースビルドするには、C++ ビルドツールチェーン（Visual Studio MSVC）や Python ヘッダーファイルが必要です。これが、pip install insightface がコンパイルエラーで失敗する原因です。

インストール失敗時の典型的なエラー

通常の pip install では以下のようなエラーが発生します：

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

これらはすべて C++ コンパイル環境の不足を意味しており、単なるパッケージ欠如ではありません。

解決手順

ステップ 1：正しい Python 環境の特定

インストールは、ComfyUI を起動する Python 環境に対して行います：

まず Python バージョンを確認します：

python --version

ポータブル版の場合は以下を実行します：

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

ステップ 2：適合する事前ビルド済み wheel の導入

Windows 環境では、ReActor コミュニティが提供している事前ビルド済みの wheel ファイルを使用します。Python のバージョンに合わせて選択してください：

ポータブル版（Windows Embedded Python）の場合は、python -m pip の部分を以下に置き換えて実行します：

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

これらはコミュニティ提供の wheel であり、公式の InsightFace PyPI プロジェクトが配布しているものではありません。信頼できる配布元だと判断できる場合だけダウンロードし、正確な URL とバージョンを記録し、可能ならバックアップ済みの環境で作業してください。リスクを判断できない場合はインストールせず、サポートされている環境か、ノード作者が文書化している依存関係の手順を使ってください。

ステップ 3：必要な場合のみ ONNX Runtime をインストール

InsightFace は推論バックエンドとして ONNX Runtime を使用します。通常は CPU 版で十分です：

python -m pip install onnxruntime

GPU での高速処理が必要な場合のみ、以下を導入します：

python -m pip install onnxruntime-gpu

※ GPU 版の ONNX Runtime は、使用中の PyTorch に紐づく CUDA/cuDNN と適合している必要があります。onnxruntime_providers_cuda.dll エラーなどが出る場合は、ONNX / ONNXRuntime 指南 を参照してください。

ステップ 4：最終手段としての NumPy 降級

InsightFace があるからといって無条件に NumPy を 1.x に降級しないでください。現在の ComfyUI 環境は NumPy 2.x に対応しています。

人脸関連プラグインで実際に NumPy の互換性エラーが出た場合のみ、以下を実行して降級を試してください：

python -m pip install "numpy<2"

その後、ComfyUI を再起動して動作を検証します。

ステップ 5：ComfyUI の再起動

インストール完了後、ComfyUI を完全に再起動します（起動プロセス中にノードの登録が行われるためです）。

インストールの検証

同じ Python 環境で以下を実行します：

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

コミュニティ提供の wheel が正常に入っている場合、0.7.3 と出力されます。

関連ガイド

• ComfyUI No Module Named 'triton'
• 修復 ComfyUI 中的 No module named 錯誤
• ONNX / ONNXRuntime 指南
• ComfyUI 依賴衝突

参照元

• InsightFace GitHub リポジトリ
• ComfyUI-ReActor リポジトリ（Community Assets）