OpenCV の配布パッケージを重ねずに cv2 のインポートを修正する

一つの名前空間に複数の配布パッケージ

パッケージのメンテナーは、標準版と contrib 版、それぞれに GUI 版と ヘッドレス版を公開しています。すべて同じ cv2 名前空間を使うため、各環境で選ぶ配布パッケージは一つだけにするよう明示しています。ヘッドレスビルドには cv2.imshow などの OpenCV GUI 機能が含まれません。ブラウザー UI を使うだけなら、これらの機能が必要とは限りません。メンテナーによるインストール手順と FAQ（英語）

変更する前に調べます。

python -m pip show opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless

失敗している ComfyUI プロセスが使うインタープリターを使用してください。パッケージを変更する前に、4 つの配布パッケージの結果と、該当ノードの要件を記録します。信頼できる cv2 をすでにインポートできる場合は、そのインタープリターで cv2.__file__ を調べ、読み込まれたコピーの場所を特定します。パッケージのメタデータに問題がなくても、手動で配置した古い cv2 ファイルが競合する場合があります。メンテナーは再インストール前に、そのような古い手動バインディングを削除するよう推奨しています。メンテナーの案内（英語）

不足とネイティブライブラリの読み込みを切り分ける

No module named cv2 の場合は、インタープリターの選択、インストール済みの配布パッケージ、インポートパスを調べます。Windows で DLL load failed が出る場合は、エラー全体を保存し、対応する Visual C++ ランタイムや、N／KN エディション向けの Media Feature Pack など、メンテナーが示すプラットフォーム固有の前提条件を確認します。これらは条件に応じて確認する項目であり、すべての環境に共通する修正ではありません。関係のないダウンロードサイトのファイルでシステム DLL を置き換えないでください。メンテナーの FAQ（英語）

配布パッケージが重複している場合は、競合を解消する前に復元可能な環境のコピーとノードの依存関係の記録を保存します。メンテナーが示す修復方法は、競合する OpenCV の配布パッケージをアンインストールし、選んだ種類を一つだけ再インストールすることです。まず、その手順をコピー上でテストしてください。パッケージのインポート確認は途中段階にすぎません。同じ ComfyUI インスタンスを再起動し、元の画像処理ノードを再実行します。GUI ウィンドウの失敗と画像読み込みの失敗は分けて記録してください。メンテナーの案内（英語）

関連する確認

• yaml、PIL、pydantic_settings が見つからない：配布パッケージ名を確認する
• MMCV のインストールと演算子不足のエラー：ビルドの組み合わせを確認する

資料の確認は 2026-09-26 に完了しました。ローカルのパッケージ変更、ネイティブインポート、画像ノードの実行、GPU による再現テストは行っていません。