ModuleNotFoundError: No module named 'cv2' in ComfyUI の修復
ComfyUI での ModuleNotFoundError: No module named 'cv2' エラーの修復。opencv-python-headless、opencv-contrib-python などの衝突の解決法。
30秒分診意思決定
実行したいワークフローが動画読み込み（VideoHelperSuite）、ポーズ検出（ControlNet DWPose）、顔交換（ReActor）などに関係していない場合、このログは単なる無視できる警告です。そのまま無視してください。 もし関連カスタムノードがエラーで停止してワークフローが中断している場合は、ComfyUI の Python 環境に対して適切な OpenCV バリアントを導入する必要があります。
ComfyUI に ModuleNotFoundError: No module named 'cv2' というエラーが表示された場合、システム全体の Python ではなく、ComfyUI が実際に使用している Python 環境に適切な OpenCV パッケージをインストールする必要があります。
Windows 環境では、複数の OpenCV パッケージ（例：opencv-python と opencv-python-headless）が同時にインストールされていると、共通の cv2 名前空間を壊してインポートエラーになる典型的な罠があります。
精確なエラーログ
コンソールまたは起動ログに以下のいずれかのエラーが出ている場合、本ガイドの対象となります：
ModuleNotFoundError: No module named 'cv2'または、以下のパッケージ欠如に関するログが該当します：
albumentations requires opencv-python-headless, which is not installed
mediapipe requires opencv-contrib-python, which is not installed
mmcv requires opencv-python, which is not installed原因
OpenCV は cv2 モジュールを提供しており、多くのカスタムノードがこれを使用して画像の縮小・拡大、切り抜き、ポーズ事前処理、カラー変換、動画フレーム処理などを実行します。
エラーの原因は主に以下の通りです：
- ComfyUI を起動する Python 環境に OpenCV パッケージが一切入っていない。
- 複数の異なる OpenCV パッケージが混在しており、共有名前空間
cv2が壊れている。 - NumPy とのバージョン不整合や、Windows のネイティブ DLL 不足によりインポートが失敗している。
OpenCV パッケージの種類と選定基準
PyPI 上の以下の公式パッケージはすべて同じ cv2 モジュールを提供します：
| パッケージ名 | 内容 | 推奨される用途 |
|---|---|---|
opencv-python | コアモジュール + GUI サポート | GUI ウィンドウ（cv2.imshow 等）が必要な場合 |
opencv-python-headless | コアモジュール、GUI なし | サーバー/バックエンド環境。ComfyUI にとって最適なデフォルトの選択肢です。 |
opencv-contrib-python | コア + 拡張モジュール + GUI | 追加アルゴリズムと GUI が必要な場合 |
opencv-contrib-python-headless | コア + 拡張モジュール、GUI なし | 追加アルゴリズムが必要だが GUI は不要な場合 |
※ 重要な規則：同じ環境に同時にインストールする OpenCV パッケージは どれか 1 つだけにしてください。混在させると必ずインポートエラーを誘発します。
解決手順
ステップ 1：正しい Python 環境の特定
インストールは、ComfyUI を起動する Python 環境に対して行います：
| インストール環境 | 実行コマンド |
|---|---|
| 公式 Windows ポータブル版 | ポータブルルートで実行：.\python_embeded\python.exe -s -m pip ... |
| 手動インストール（Git + venv） | venv を有効化後に実行：python -m pip ... |
| ComfyUI Desktop または他のランチャー | アプリ内蔵のコンソール環境を使用。 |
ステップ 2：インストール状況の確認
現在インストールされている OpenCV パッケージをリストアップします：
python -m pip list | findstr opencvポータブル版の場合：
.\python_embeded\python.exe -s -m pip list | findstr opencvもし複数の OpenCV パッケージが検出された場合は、一度すべてクリーンアップする必要があります。
ステップ 3：クリーンアップとインストール
ケース 1：OpenCV パッケージが何も入っていない場合
python -m pip install opencv-python-headlessケース 2：インストールされているがインポートエラーになる、または複数入っている場合
一度すべてアンインストールした上で、headless 版のみを単一インストールします：
python -m pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless
python -m pip install opencv-python-headlessケース 3：NumPy のバージョン競合がある場合 NumPy のバージョンを無条件に 1.x に降級しないでください。現在の ComfyUI 環境は NumPy 2.x に対応しています。 もし特定の古いカスタムノードで NumPy のバージョン互換性エラーが出た場合のみ、環境をバックアップの上で NumPy の降級を試してください。
ケース 4：特定のカスタムノードが contrib モジュールを要求する場合
opencv-python-headless の上から重ねてインストールするのではなく、一度アンインストールした後に opencv-contrib-python-headless のみをインストールしてください。
ステップ 4：検証
同じ環境で以下を実行し、インポートできるか確認します：
python -c "import cv2; print(cv2.__version__)"バージョン番号が正常に出力されたら、ComfyUI を完全に再起動します。
関連ガイド
参照元
実際の ComfyUI 環境で起きている問題なら、まず無料で Wonderful Launcher を使って確認してください。ランチャー内の修復フロー、タスクログ、実行環境チェックを一か所で確認できます。クレジットは画像生成と従量ツール用です。
Wonderful Launcher をダウンロードクレジットプランを見るDid this fix your issue?
Your answer helps prioritize verified ComfyUI repairs.
Nunchaku 不足
ComfyUI での ModuleNotFoundError: No module named 'nunchaku' の修復。nunchaku.lora、nunchaku.utils、nunchaku.models、NunchakuFluxLoraLoader、NunchakuFluxDiTLoader のロード失敗への対応。
SAM 不足
Fix ModuleNotFoundError: No module named 'groundingdino' or 'segment_anything' in ComfyUI SAM, GroundingDINO, masking, and segmentation workflows.