No module named 'cv2' in ComfyUI: OpenCV Fix

Symptoms

When ComfyUI starts, the terminal log shows:

ModuleNotFoundError: No module named 'cv2'

or:

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

Sometimes the terminal does not mention cv2 first. It may appear through pip check lines like:

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 package names are different, but they point to the same shared OpenCV family.

Cause

OpenCV provides the cv2 module used by many custom nodes for resizing, cropping, pose preprocessing, segmentation masks, video frames, and color conversion. ControlNet helper nodes, VideoHelperSuite, Impact Pack, face tools, and many workflow utility nodes can depend on it.

This error is typically caused by one of the following:

1. No OpenCV package is installed in the Python environment that starts ComfyUI.
2. Multiple OpenCV package flavors are installed and overwrite the shared cv2 namespace.
3. OpenCV imports but fails because of a NumPy or native DLL mismatch.

OpenCV package naming

The official PyPI OpenCV packages all provide the same cv2 module:

For ComfyUI, opencv-python-headless is usually the safer default because ComfyUI does not need OpenCV GUI windows, and headless avoids extra Qt/GUI dependencies.

Important: keep only one OpenCV package flavor installed at a time.

Packages that often surface the OpenCV error

In ComfyUI support cases, OpenCV problems often show up through the dependent package rather than through cv2 directly:

Do not install every OpenCV flavor just because different packages name different variants. Pick one flavor that fits the environment, verify import cv2, and then test the workflow that actually needs it.

Severity

Medium - OpenCV is foundational for many custom nodes, but install it only in the Python environment that actually runs ComfyUI.

Before installing: use the correct Python

Solution

Step 1: Diagnose the current state

Check which OpenCV packages are installed:

python -m pip list | findstr opencv

For the official Windows portable package:

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

If multiple OpenCV packages appear, clean them up before reinstalling one flavor.

Step 2: Clean up and install

Case 1: No OpenCV package is installed

python -m pip install opencv-python-headless

Case 2: Already installed but throwing errors, or multiple OpenCV packages are 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

Case 3: NumPy conflict during installation or import

Do not downgrade NumPy globally as a first move. Current ComfyUI environments can legitimately use NumPy 2.x, while older plugins may still expect NumPy 1.x.

If the log names a specific NumPy/OpenCV compatibility error, choose a single OpenCV version that supports the NumPy stack you are keeping, or isolate the old plugin in a separate environment.

Case 4: pip check says another package requires OpenCV

If the only symptom is a pip check line, first check whether the plugin imports and whether your workflow uses it. A missing OpenCV declaration is not always a fatal ComfyUI startup error.

If the workflow is blocked, install one OpenCV flavor and test:

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

If a package specifically needs contrib modules, use opencv-contrib-python-headless instead of stacking it on top of opencv-python-headless.

Step 3: Verify the installation

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

If a version number is printed, restart ComfyUI and check whether the plugin imports.

Still not resolved?

If cv2 still fails after cleanup, collect:

• output of python -m pip list | findstr opencv
• output of python -m pip list | findstr numpy
• the full IMPORT FAILED traceback
• your install type: portable, Desktop, manual venv, or managed launcher

Then use expert help if you need the fastest recovery path.

Source References

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