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 这个模块，区别如下：

包名	内容	适用场景
opencv-python	核心模块 + GUI 支持	需要 GUI 窗口（如 cv2.imshow）
opencv-python-headless	核心模块，无 GUI	服务器 / 后台处理（推荐）
opencv-contrib-python	核心 + 扩展模块 + GUI	需要额外算法（如 SIFT）
opencv-contrib-python-headless	核心 + 扩展模块，无 GUI	服务器上需要扩展算法

对于 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>=2.0 的版本冲突提示，可以指定一个兼容性更好的 opencv 版本：

pip install opencv-python-headless==4.10.0.84

第三步：验证安装

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

如果正常输出版本号，说明安装成功。重启 ComfyUI 即可。

仍然无法解决？

如果按照上述步骤操作后问题依旧，请通过应用内的「联系我们」按钮联系技术支持。