InsightFace のインストールまたは初期化に失敗する：パッケージと FaceID 用ファイルを分けて確認する

症状と対象範囲

FaceID は、Python パッケージのインストール、インポート、InsightFace 解析モデルの準備、画像の実行のいずれかで失敗することがあります。これらは異なる段階です。最初に関係する traceback を残してください。

検索の手掛かりとなるエラーの断片です。詳細はバージョンや環境によって異なります。

No module named 'insightface'
Failed building wheel
ExecutionProvider

出典から確認できること

IPAdapter Plus は FaceID に insightface が必要だとし、ほとんどの FaceID アダプターでは対応する LoRA も必要だとしています。ピン留めしたローダーは FaceAnalysis をインポートし、ComfyUI のモデルディレクトリ内にモデルルートを設定し、選択したプロバイダー名の末尾に ExecutionProvider を付けて渡し、prepare を呼び出します。別の名前が指定されない限り、既定の解析モデルは buffalo_l です。Python パッケージをインストールしただけでは、解析モデル、ONNX Runtime プロバイダー、アダプター、LoRA が利用可能だとは確認できません。IPAdapter README（英語） ピン留めしたローダー（英語） ONNX Runtime プロバイダー（英語）

区別すべき状況

1. insightface が別のインタープリターにインストールされているため、ComfyUI を実行している Python プロセスからインポートできない。

2. pip が特定のパッケージの解決またはビルドに失敗している。失敗した配布パッケージとバージョンを特定して診断する。現行の InsightFace 2.0 の PyPI リリースには Python のバージョンやプラットフォームに依存しない wheel があるため、「InsightFace に互換性のあるビルド済み wheel がない」という一般的な主張は正確ではない。依存パッケージ、古いバージョン、ローカルビルドで失敗することはある。新しいリリースが、インストール済みの IPAdapter ノードと自動的に互換性を持つとは限らない。

3. インポートは成功するが、指定した解析モデルを利用できない。または、選択した ONNX Runtime 実行プロバイダーを初期化できない。アダプター、CLIP Vision、FaceID LoRA の検出は、その後に別途確認する。

確認手順

これは編集上の手順であり、お使いのマシンの診断ではありません。

手順 1. 最初に失敗したコマンドまたはノードと、完全な traceback を記録します。ComfyUI を起動するのと同じインタープリターで python -m pip show insightface onnxruntime onnxruntime-gpu と単純な import insightface を確認します。シェルの既定の Python が ComfyUI のインタープリターだと決めつけないでください。

手順 2. インストールに失敗した場合は、失敗した配布パッケージ、Python のバージョン、プラットフォーム、パッケージのバージョンを正確に記録します。python -m pip debug で互換性のあるタグを調べます。バージョンを変えたりサードパーティー製 wheel をインストールしたりする前に、パッケージの公式ファイルとビルド要件を確認します。

手順 3. インポートが成功したら、選択した FaceID プリセット、InsightFace モデル名、設定済みのモデルルート、プロバイダーを記録します。同じ環境で onnxruntime.get_available_providers() が返すプロバイダーと照合します。モデルパッケージとそのライセンスは、Python パッケージとは分けて確認します。

手順 4. ワークフローのコピーで、使用許可のある画像を 1 枚使い、サポート対象の FaceID アダプターと対応 LoRA、必要な CLIP Vision ファイルをテストします。新たに発生したアダプターエラー、LoRA エラー、形状エラーは別段階のものとして残します。ONNX Runtime または InsightFace を変更する前に、依存関係の制約を再確認します。

完了の確認

ComfyUI のインタープリターから InsightFace をインポートでき、要求した解析モデルが利用可能なプロバイダーで準備でき、正しく対応付けた最小限の FaceID ワークフローがサンプリングまで進むことを確認します。pip コマンドが成功しただけでは、後続の段階が成功した証明にはなりません。

制限と注意点

InsightFace のコードと学習済みモデルパッケージでは利用条件が異なります。上流のモデルガイドでは、公開されている学習済みモデルの用途を非商用研究としています。対象の重みの利用条件を確認し、個人を特定できる人物の画像を使う場合は許可を得てください。このサイトでは、パッケージのインストール、モデルのダウンロード、プロバイダーのテスト、GPU ワークフローの実行をしていません。

参照した原文資料

• IPAdapter Plus README（英語）（確認日：2026-09-26）
• ピン留めした IPAdapter InsightFace ローダー（英語）（確認日：2026-09-26）
• pip debug リファレンス（英語）（確認日：2026-09-26）
• InsightFace の PyPI リリースファイル（英語）（確認日：2026-09-26）
• ONNX Runtime 実行プロバイダー（英語）（確認日：2026-09-26）
• InsightFace のモデルガイドと利用条件（英語）（確認日：2026-09-26）

資料と英語原文を確認した日付は 2026-09-26 です。パッケージと実行時の動作はインストール済みのバージョンに照らして確認する必要があります。互換性は保証していません。

関連するトラブルシューティング記事とガイド

• パッケージを導入したのに ComfyUI で ModuleNotFoundError が出る
• No matching distribution found：Python のタグ、プラットフォーム、パッケージ名を確認する
• IPAdapter Plus リファレンス：プリセット、ビジョンエンコーダー、FaceID の依存関係