ComfyUI の依存関係競合（Dependency Conflicts）の解決
カスタムノードの導入、Torch のダウングレード、pip の衝突、プラグイン読み込みエラー、パッケージのバージョン固定による ComfyUI の依存関係競合を解決する方法。
テスト環境
- OS： Windows 10 / 11
- ランチャー： Wonderful Launcher v1.x
- ComfyUI： ポータブル版 / マネージドインストール
- Python： 3.11+
- CUDA / Torch： CUDA 12.x / Torch 2.x
- 検証日： 2026-05-19
起動エラーログやコマンドラインに comfyui dependency conflicts、custom node broke environment などの問題が表示された場合、すぐに再インストールを行わないでください。どのカスタムノードまたはパッケージの変更が環境を壊したのかを特定し、最小限の範囲で修復するのが最も安全な解決へのアプローチです。
依存関係の競合（Dependency Conflict）は、多くの ComfyUI 環境において「目に見えないキラー」です。あるプラグインを導入した際、そのプラグインが自動でインストールした依存パッケージが、既存の PyTorch、NumPy、OpenCV 等のバージョンを勝手に書き換えてしまい、昨日まで動いていたワークフローが突然動かなくなる現象を引き起こします。
何が原因で壊れたのかを突き止め、環境への破壊を最小限に抑える方法を学びましょう。
早期に検知すべき典型的な衝突パターン
以下のエラーパターンは発生頻度が高いため、覚えておくと便利です：
| エラーのヒント | 原因 | 推奨される対策 |
|---|---|---|
qwen-tts requires transformers==... | 音声系ノードが特定の Transformers バージョンを強制ロック | 該当ワークフローが本当に必要でない限り、環境全体の Transformers バージョンを変更しないこと |
mediapipe requires numpy<2 | 古い MediaPipe パッケージが NumPy 2.x 以上と衝突 | MediaPipe がワークフローの動作に不可欠である場合を除き、NumPy のグローバルな降級（ダウングレード）は避ける |
opencv-python-headless と opencv-python の衝突 | 複数の OpenCV パッケージが同じ cv2 名前空間を奪い合っている | 不要な OpenCV パッケージをアンインストールし、1つだけに整理する |
torchscale requires timm==... | 古いビジョンスタックが更新版の timm パッケージと競合 | どのカスタムノードが該当パッケージを要求しているかを確認する |
pip install mmcv exited with code 1 | MMCV のビルドが現在の Python/Torch/CUDA と不一致 | MMCV 専用のインストールガイドを参照する |
解決手順の概要
| 発生している現象 | 原因 | 優先ステップ |
|---|---|---|
| プラグイン導入直後に ComfyUI がエラーを吐く | プラグインが共有パッケージを書き換えた | 起動コンソールの IMPORT FAILED を確認し、pip check を実行 |
Torch not compiled with CUDA enabled | コアの PyTorch ランタイムが CPU 専用版にダウングレードされた | まず Torch ランタイムを復旧させ、その後にプラグインパッケージを修復 |
No module named 'triton' または sageattention | 加速パッケージの不足 | 専用のガイドを確認し、無条件に pip install triton を実行しないこと |
cv2 や ONNX のインポートエラー | ネイティブコンパイルされた wheel パッケージの競合 | パッケージバージョンが現在の Python および CUDA バージョンと合っているか確認 |
ステップ 1：診断と分析
起動ログの確認
ComfyUI の起動コンソールログを確認し、IMPORT FAILED の行を見つけます：
IMPORT FAILED: ComfyUI-ExampleNode
ModuleNotFoundError: No module named 'somepackage'pip check による競合の検出
ComfyUI を起動している正確な Python 環境で以下のコマンドを実行します：
| インストール環境 | 実行コマンド |
|---|---|
| 公式 Windows ポータブル版 | ポータブルルートで実行：.\python_embeded\python.exe -s -m pip check |
| 手動インストール（Git + venv） | 仮想環境（venv）を有効化後に実行：python -m pip check |
出力例：
some-plugin 1.0 requires numpy<2, but you have numpy 2.4.4ステップ 2：エラーの分類
A. 致命的な競合（直ちに修正が必要）
torchパッケージの破損、または CPU 専用版へのダウングレード。- ワークフローに不可欠なプラグインで発生している
ModuleNotFoundError。 DLL load failed while importing cv2などのバイナリのロード失敗。
B. 無害な競合（無視してよいもの）
pip checkでバージョン不一致の警告が出ているが、ComfyUI 自体は正常に起動し、プラグインもロードされ、画像生成も動いている場合。- 黄金規則：すべてが正常に動作している場合は、単に
pip checkの警告を消すためだけにパッケージを変更しないでください。
ステップ 3：修復プロトコル
規則 1：主要パッケージの保護
torch、numpy、pillow、opencv-python などのコアパッケージは、他のプラグインの自動インストールによって変更されないように保護する必要があります。インストール前に以下を実行して競合をシミュレートできます：
python -m pip install -r requirements.txt --dry-runもし Torch や NumPy が意図せず上書きされそうになっている場合は、インストールを一旦中断してください。
規則 2：正しい Python 実行ファイルの指定
一般的なシステム全体の Python 環境に対して pip install を実行しないよう注意してください。
| インストール環境 | 推奨コマンド |
|---|---|
| 公式ポータブル版 | .\python_embeded\python.exe -s -m pip install <パッケージ名> |
| 手動インストール（venv） | venv 有効化状態で python -m pip install <パッケージ名> |
関連ガイド
実際の ComfyUI 環境で起きている問題なら、まず無料で Wonderful Launcher を使って確認してください。ランチャー内の修復フロー、タスクログ、実行環境チェックを一か所で確認できます。クレジットは画像生成と従量ツール用です。
Wonderful Launcher をダウンロードクレジットプランを見るDid this fix your issue?
Your answer helps prioritize verified ComfyUI repairs.