ComfyUI: ModuleNotFoundError: No module named 'cv2' (fix)

ModuleNotFoundError: No module named 'cv2' in ComfyUI means a custom node imports OpenCV but it isn't installed in ComfyUI's Python. The package is opencv-python, not cv2. We reproduced it on v0.37.0 and fixed it.

1. The error

ComfyUI v0.37.0 (CPython 3.11, torch 2.9.0+cpu) with ComfyUI_InstantID and ComfyUI-Impact-Subpack in custom_nodes/, and OpenCV not installed in ComfyUI's Python (traceback shortened):

[WARNING] Traceback (most recent call last):
  ...
  File "ComfyUI/custom_nodes/ComfyUI_InstantID/__init__.py", line 1, in <module>
    from .InstantID import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
  File "ComfyUI/custom_nodes/ComfyUI_InstantID/InstantID.py", line 7, in <module>
    import cv2
ModuleNotFoundError: No module named 'cv2'

[WARNING] Cannot import ComfyUI/custom_nodes/ComfyUI_InstantID module for custom nodes: No module named 'cv2'

Impact Subpack fails the same way at modules/subcore.py line 3. The startup summary:

[INFO]    0.0 seconds (IMPORT FAILED): ComfyUI/custom_nodes/ComfyUI_InstantID
[INFO]    0.0 seconds (IMPORT FAILED): ComfyUI/custom_nodes/ComfyUI-Impact-Subpack

ComfyUI itself starts (exit code 0; its own requirements.txt has no OpenCV), but every node pack that imports cv2 is marked IMPORT FAILED and its nodes are missing.

2. Don't pip install cv2

cv2 is the import name; the package on PyPI is called opencv-python (or opencv-python-headless):

$ python -m pip install cv2
ERROR: Could not find a version that satisfies the requirement cv2 (from versions: none)
ERROR: No matching distribution found for cv2

3. Fix: install OpenCV into ComfyUI's Python

python -m pip install opencv-python-headless

That installed opencv-python-headless 5.0.0.93 (cv2.__version__ 5.0.0) and after a restart both packs loaded:

[INFO]    0.0 seconds: ComfyUI/custom_nodes/websocket_image_save.py
[INFO]    0.0 seconds: ComfyUI/custom_nodes/comfyui-various
[INFO]    0.0 seconds: ComfyUI/custom_nodes/ComfyUI-GGUF
[INFO]    0.1 seconds: ComfyUI/custom_nodes/ComfyUI-Impact-Subpack
[INFO]    0.2 seconds: ComfyUI/custom_nodes/ComfyUI_InstantID

Impact Subpack's requirements.txt asks for opencv-python-headless; InstantID's does not list OpenCV at all and gets opencv-python through its insightface dependency, so pip install -r requirements.txt in each node folder also fixes it. The headless build has no GUI functions (cv2.imshow), which ComfyUI nodes don't need. Use the Python that runs main.py: activate the venv first, or on the Windows portable build run python_embeded\python.exe -m pip install opencv-python-headless from the ComfyUI_windows_portable folder.

Related: numpy.core.multiarray failed to import (cv2) · ComfyUI: No module named 'insightface' · ComfyUI: No module named 'ultralytics' · ComfyUI: No module named 'yaml' (wrong Python)

Frequently asked questions

Why does pip install cv2 fail?

There is no cv2 package on PyPI; cv2 is the import name. Install opencv-python or opencv-python-headless.

Does ComfyUI itself need OpenCV?

No. ComfyUI v0.37.0 starts without it; only custom nodes that import cv2 fail.

Written with AI assistance. Measured on 2026-10-24 on Linux, CPython 3.11.17: ComfyUI v0.37.0, torch 2.9.0+cpu, ComfyUI_InstantID at commit 72495e8 and ComfyUI-Impact-Subpack V1.3.5, without and with opencv-python-headless 5.0.0.93. Output pasted unedited except shortened paths and a trimmed traceback. PlainTables is our extension; ComfyUI, the node packs and OpenCV are free.