ModuleNotFoundError: No module named 'cv2' in ComfyUI

ModuleNotFoundError: No module named 'cv2' (or Cannot import ... module for custom nodes: No module named 'cv2') means OpenCV is missing, installed into the wrong Python, or conflicted by multiple opencv-* packages. It can also surface indirectly through 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

Those names differ but point to the same shared OpenCV family. OpenCV provides the cv2 module used by ControlNet helpers, VideoHelperSuite, Impact Pack, face tools, and many utility nodes.

Severity: medium — install it only in the Python environment that actually runs ComfyUI.

Triage

The error is typically one of:

1. No OpenCV package installed in ComfyUI's Python.
2. Multiple OpenCV flavors overwriting the shared cv2 namespace.
3. OpenCV imports but fails on a NumPy or native DLL mismatch.

OpenCV package naming

All official PyPI OpenCV packages provide the same cv2 module. Keep only one flavor installed at a time.

opencv-python-headless is usually the safer ComfyUI default (no GUI windows, no extra Qt/GUI dependencies). Packages that often surface the error through a dependency: albumentations/albucore/rembg (need headless), mediapipe/inference-gpu (need contrib), and pixeloe/facexlib/groundingdino-py/supervision/ultralytics/mmcv (need opencv-python). Pick one flavor that fits, verify import cv2, then test the workflow.

Use the correct Python

Step 1: Diagnose the current state

python -m pip list | findstr opencv

For the official Windows portable package, use .\python_embeded\python.exe -s -m pip list | findstr opencv. If multiple OpenCV packages appear, clean up before reinstalling one flavor.

Step 2: Clean up and install

No OpenCV package installed:

python -m pip install opencv-python-headless

Already installed but erroring, or multiple flavors present:

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 conflict during install or import: do not downgrade NumPy globally as a first move — current ComfyUI environments can use NumPy 2.x. If the log names a specific NumPy/OpenCV error, choose a single OpenCV version that supports the NumPy stack you are keeping, or isolate the old plugin in a separate environment.

pip check says another package requires OpenCV: first check whether the plugin imports and whether your workflow uses it — a missing declaration is not always fatal. If the workflow is blocked, install one flavor and test. If a package specifically needs contrib modules, use opencv-contrib-python-headless instead of stacking it on opencv-python-headless.

Step 3: Verify

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

If a version prints, restart ComfyUI and check whether the plugin imports.

Still not resolved?

Collect python -m pip list | findstr opencv, python -m pip list | findstr numpy, the full IMPORT FAILED traceback, and your install type before choosing a support path.

Source References

• ComfyUI troubleshooting overview
• ComfyUI custom node troubleshooting guide
• ComfyUI model troubleshooting guide
• opencv-python package on PyPI