ModuleNotFoundError: No module named 'cv2' in ComfyUI

如果你搜索的是 ModuleNotFoundError: No module named 'cv2' 或 comfyui no module named cv2，请先检查 OpenCV 是否缺失、是否安装到了错误的 Python 环境，或是否因多个 opencv-* 包而产生冲突。

症状

ComfyUI 启动时，终端日志显示：

ModuleNotFoundError: No module named 'cv2'

或：

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

有时终端不会首先提到 cv2，而是通过 pip check 的输出行显示：

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 系列。

原因

OpenCV 提供了 cv2 模块，许多自定义节点使用它来完成图像缩放、裁剪、姿态预处理、分割掩码、视频帧处理和颜色转换等操作。ControlNet 辅助节点、VideoHelperSuite、Impact Pack、人脸工具以及许多工作流实用节点都可能依赖它。

此错误通常由以下原因之一引起：

1. 启动 ComfyUI 的 Python 环境中未安装任何 OpenCV 包。
2. 安装了多个 OpenCV 包变体，导致共享的 cv2 命名空间被覆盖。
3. OpenCV 可以导入，但因 NumPy 或原生 DLL 不匹配而失败。

OpenCV 包命名说明

PyPI 上官方的 OpenCV 包均提供相同的 cv2 模块：

对于 ComfyUI，opencv-python-headless 通常是更安全的默认选择，因为 ComfyUI 不需要 OpenCV GUI 窗口，且 headless 版本可以避免额外的 Qt/GUI 依赖。

重要提示： 同一时间只保留一个 OpenCV 包变体。

常见触发 OpenCV 错误的依赖包

在 ComfyUI 的支持案例中，OpenCV 问题通常通过依赖包而非直接通过 cv2 暴露出来：

不要因为不同的包需要不同的变体就把所有 OpenCV 变体都安装上。选择一个适合当前环境的变体，验证 import cv2 可用，然后测试实际需要它的工作流。

严重程度

中等 - OpenCV 是许多自定义节点的基础依赖，但请只在实际运行 ComfyUI 的 Python 环境中安装它。

安装前：确认使用正确的 Python

解决方案

第一步：诊断当前状态

检查已安装了哪些 OpenCV 包：

python -m pip list | findstr opencv

对于官方 Windows 便携包：

.\python_embeded\python.exe -s -m pip list | findstr opencv

如果出现多个 OpenCV 包，请在重新安装某一变体之前先清理它们。

第二步：清理并安装

情况一：未安装任何 OpenCV 包

python -m pip install opencv-python-headless

情况二：已安装但报错，或存在多个 OpenCV 包

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

情况三：安装或导入时出现 NumPy 冲突

不要第一时间全局降级 NumPy。当前的 ComfyUI 环境可以合法使用 NumPy 2.x，而一些较旧的插件可能仍然期望使用 NumPy 1.x。

如果日志中指出了具体的 NumPy/OpenCV 兼容性错误，请选择一个支持你所保留的 NumPy 版本的 OpenCV 版本，或将旧插件隔离到单独的环境中。

情况四：pip check 提示另一个包需要 OpenCV

如果唯一的症状是 pip check 输出行，请先检查该插件是否能正常导入，以及你的工作流是否真正使用到了它。缺少 OpenCV 声明并不总是会导致 ComfyUI 启动致命错误。

如果工作流被阻塞，请安装一个 OpenCV 变体并进行测试：

python -m 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 并检查插件是否能正常导入。

仍未解决？

如果清理后 cv2 仍然失败，请收集以下信息：

• python -m pip list | findstr opencv 的输出
• python -m pip list | findstr numpy 的输出
• 完整的 IMPORT FAILED 报错堆栈
• 你的安装类型：便携包、Desktop、手动 venv 或托管启动器

如果仍然无法解决，请先保存这些信息，再回到第一条真实 IMPORT FAILED 继续做最小化修复。

参考资料

• ComfyUI 故障排除概述
• ComfyUI 自定义节点故障排除指南
• ComfyUI 模型故障排除指南
• PyPI 上的 opencv-python 包