OpenCV (cv2) Missing or Conflicting

Symptoms

When ComfyUI starts, the terminal log shows:

ModuleNotFoundError: No module named 'cv2'

Or:

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

Cause

OpenCV (cv2) is a computer vision library used by many custom nodes for image processing (resizing, cropping, color conversion, etc.). Popular nodes such as ControlNet, VideoHelperSuite, and Impact Pack all depend on it.

This error is typically caused by one of the following:

1. OpenCV is not installed -- no opencv package exists in the environment.
2. Multiple opencv packages are installed, causing conflicts -- opencv-python, opencv-python-headless, opencv-contrib-python, and similar packages all share the same cv2 namespace. Installing more than one causes them to overwrite each other, corrupting the module.
3. Incompatible numpy version -- newer versions of opencv require numpy>=2.0, while other packages may require numpy<2.0. This version conflict can prevent cv2 from importing.

OpenCV package naming

There are four official opencv packages on PyPI. They all provide the cv2 module but differ as follows:

Package	Contents	Use case
opencv-python	Core modules + GUI support	When GUI windows are needed (e.g. cv2.imshow)
opencv-python-headless	Core modules, no GUI	Servers / background processing (recommended)
opencv-contrib-python	Core + extra modules + GUI	When extra algorithms are needed (e.g. SIFT)
opencv-contrib-python-headless	Core + extra modules, no GUI	Extra algorithms on servers

For ComfyUI, opencv-python-headless is recommended: it has no Qt/GUI dependencies, is smaller, and avoids conflicts with packages like PyQt5. ComfyUI does not need OpenCV's GUI features.

Important: only one of these four packages should be installed at a time. Installing multiple packages will corrupt or break the cv2 module.

Severity

Medium -- OpenCV is a foundational dependency for many custom nodes. Installing it is strongly recommended.

Solution

Step 1: Diagnose the current state

Open the Environments page in Wonderful Launcher, find the Terminal area, and run the following command to check which opencv packages are installed:

pip list | findstr opencv

Example output:

opencv-python           4.10.0.84
opencv-python-headless  4.10.0.84

If multiple opencv packages appear (as shown above), there is a conflict that needs to be cleaned up.

Step 2: Clean up and install

Case 1: No opencv package is installed

Simply install it:

pip install opencv-python-headless

Case 2: Already installed but throwing errors, or multiple opencv packages are present

Uninstall all opencv packages first, then reinstall a single one:

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

pip install opencv-python-headless

Case 3: numpy version conflict during installation

If the installation reports a version conflict involving numpy>=2.0, pin a more compatible opencv version:

pip install opencv-python-headless==4.10.0.84

Step 3: Verify the installation

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

If a version number is printed, the installation was successful. Restart ComfyUI.

Still not resolved?

If the issue persists after following the steps above, contact support through the "Contact Us" button in the app.