OpenCV (cv2) 缺失或衝突

症狀

ComfyUI 啟動時，終端日誌中出現：

ModuleNotFoundError: No module named 'cv2'

或者：

Cannot import ... module for custom nodes: No module named 'cv2'

原因

OpenCV（cv2）是一個計算機視覺庫，被大量插件用於圖片處理（縮放、裁剪、顏色轉換等）。ControlNet、VideoHelperSuite、Impact Pack 等常用插件都依賴它。

這個錯誤通常由以下原因之一引起：

1. 未安裝 OpenCV — 環境中沒有任何 opencv 包。
2. 安裝了多個 opencv 包導致衝突 — opencv-python、opencv-python-headless、opencv-contrib-python 等包共用同一個 cv2 命名空間，同時安裝多個會互相覆蓋，導致模塊損壞。
3. numpy 版本不兼容 — 較新版本的 opencv 要求 numpy>=2.0，而其他包可能要求 numpy<2.0，版本衝突會導致 cv2 無法正常導入。

opencv 包的命名說明

PyPI 上有四個官方 opencv 包，它們提供的都是 cv2 這個模塊，區別如下：

對於 ComfyUI 場景，推薦使用 opencv-python-headless：它不依賴 Qt/GUI 庫，體積更小，也避免了與 PyQt5 等包的衝突。ComfyUI 本身不需要 OpenCV 的 GUI 功能。

重要：這四個包只能安裝其中一個。 同時安裝多個會導致 cv2 模塊損壞或無法導入。

嚴重程度

中 — OpenCV 是很多插件的基礎依賴，建議安裝。

解決方法

第一步：診斷當前狀態

在 Wonderful Launcher 中打開「環境」頁面，找到終端（Terminal）區域，輸入以下命令檢查已安裝的 opencv 包：

pip list | findstr opencv

可能的輸出示例：

opencv-python           4.10.0.84
opencv-python-headless  4.10.0.84

如果同時出現了多個 opencv 包（如上所示），說明存在衝突，需要先清理。

第二步：清理並安裝

情況一：沒有安裝任何 opencv 包

直接安裝即可：

pip install opencv-python-headless

情況二：已安裝但報錯，或安裝了多個 opencv 包

先卸載所有 opencv 包，再重新安裝一個：

pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless

pip install opencv-python-headless

情況三：安裝時提示 numpy 版本衝突

不要把全域降級 NumPy 當作第一步。現行 ComfyUI 環境可以合理地使用 NumPy 2.x，但部分較舊的插件仍可能要求 NumPy 1.x。

只有在日誌明確指出某個 NumPy / OpenCV 相容性錯誤時，才選擇一個與你準備保留的 NumPy 堆疊相容的單一 OpenCV 版本，或將舊插件隔離到另一個環境。不要只為了消除提示，就隨意釘選 OpenCV 或全域降級 NumPy。

情況四：pip check 顯示其他套件需要 OpenCV

若唯一症狀只是 pip check 的一行提示，先確認插件能否匯入，以及你的工作流是否真的會使用它。缺少 OpenCV 宣告不一定會讓 ComfyUI 無法啟動。

如果工作流確實被阻擋，安裝一種 OpenCV 套件後再驗證：

pip install opencv-python-headless
python -c "import cv2; print(cv2.__version__)"

若某個套件明確需要 contrib 模組，請改用 opencv-contrib-python-headless，不要把它和 opencv-python-headless 疊加安裝。

第三步：驗證安裝

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

如果正常輸出版本號，說明安裝成功。重啟 ComfyUI 即可。

仍然無法解決？

如果按照上述步驟操作後問題依舊，請通過應用內的「聯繫我們」按鈕聯繫技術支持。