报错 No module named 'cv2'（controlnet_aux / WanVideoWrapper 等节点导入失败）

File "C:\ComfyUI_windows_portable_nightly_pytorch\ComfyUI\custom_nodes\comfyui_controlnet_aux\utils.py", line 4, in <module>
import cv2
ModuleNotFoundError: No module named 'cv2'
Cannot import C:\ComfyUI_windows_portable_nightly_pytorch\ComfyUI\custom_nodes\comfyui_controlnet_aux module for custom nodes:
No module named 'cv2'

现象与触发场景

常见触发场景：

• 用 update_comfyui_and_python_dependencies.bat 更新依赖后，opencv 被覆盖或卸载，节点随即报缺 cv2
• git clone 节点后只重启没跑 requirements.txt
• 已经 pip install opencv-python 了，但仍然报错（装到了另一个 Python 解释器）

根因

• cv2 由 opencv-python / opencv-python-headless 提供，它不在 ComfyUI 核心依赖里，必须由节点自己声明并安装
• 节点在 __init__.py 顶层 import cv2，缺包直接导致整个节点目录导入中断
• 依赖更新脚本或节点安装把 opencv 相关包替换/降级/卸载，但未同步装回

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

1. 用 ComfyUI 自带解释器安装 opencv
   先确认解释器（便携版为 python_embeded\python.exe），再安装。服务器/无桌面环境建议装 headless 版本，避免缺 GUI 依赖。
   ..\..\python_embeded\python.exe -m pip install opencv-python
   ..\..\python_embeded\python.exe -m pip install opencv-python-headless
2. 走该节点自己的 requirements.txt
   从该节点目录执行它声明的依赖清单，比手工猜包名可靠（例如 controlnet_aux 的 requirements.txt 同时声明了 opencv、scikit-image、onnxruntime 等）。
   cd ComfyUI\custom_nodes\comfyui_controlnet_aux
   ..\..\..\python_embeded\python.exe -m pip install -r requirements.txt
3. 排查是否装进了错误的 Python
   如果 pip 显示 Successfully installed 但报错不变，用 ComfyUI 的解释器直接验证模块能否导入，并打印模块路径，判断是否落到了另一个环境。
   ..\..\python_embeded\python.exe -c "import cv2; print(cv2.__file__)"

验证是否修好

补充说明

同类高频缺失模块还有 skimage（scikit-image）、onnxruntime、facexlib、ultralytics 等，排查手法完全相同：看 Cannot import 后面那句缺什么，就用 ComfyUI 的解释器装什么。

来源

1. [71] （节点仓库 issue）　ComfyUI - Control Net Aux - ModuleNotFoundError: No module named 'cv2'　https://github.com/Fannovel16/comfyui_controlnet_aux/issues/153
2. [72] （节点仓库 issue）　IMPORT FAILED: ModuleNotFoundError: No module named 'cv2' · Issue #674　https://github.com/kijai/ComfyUI-WanVideoWrapper/issues/674

本条报错提到的节点仓库

下面这些节点仓库的名字出现在本条报错的正文里。这里只说「名字出现过」，没有断定问题就是它引起的； 点进去可以看这个包的用途、适配模型与下载量。

这条报错要用到的东西

按本条报错所属的类别（依赖缺失与自定义节点安装失败）列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

同一类别的其他条目

返回报错库