No module named 'cv2' in ComfyUI: OpenCV-Fix

Symptome

Beim Start von ComfyUI taucht im Terminal oft Folgendes auf:

ModuleNotFoundError: No module named 'cv2'

oder:

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

Manchmal steht cv2 nicht an erster Stelle. Stattdessen siehst du pip check-Meldungen wie:

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

Die Paketnamen unterscheiden sich, verweisen aber auf dieselbe OpenCV-Familie.

Ursache

OpenCV stellt das Modul cv2 bereit, das viele Custom Nodes für Resize, Crop, Pose-Preprocessing, Segmentierung, Video-Frames und Farbkonvertierung verwenden. ControlNet-Helfer, VideoHelperSuite, Impact Pack, Face-Tools und viele Workflow-Hilfs-Nodes hängen davon ab.

Typische Ursachen:

1. In der Python-Umgebung, die ComfyUI startet, ist gar kein OpenCV-Paket installiert.
2. Mehrere OpenCV-Varianten sind gleichzeitig installiert und überschreiben gemeinsam den cv2-Namespace.
3. OpenCV importiert formal, scheitert aber wegen NumPy- oder nativer DLL-Konflikte.

OpenCV-Paketnamen richtig einordnen

Alle offiziellen PyPI-OpenCV-Pakete liefern am Ende dasselbe cv2-Modul:

Für ComfyUI ist opencv-python-headless meist die sicherste Wahl, weil ComfyUI selbst keine OpenCV-GUI-Fenster benötigt.

Wichtig: Installiere immer nur eine OpenCV-Variante gleichzeitig.

Pakete, die OpenCV-Probleme oft nur indirekt anzeigen

Installiere nicht alle OpenCV-Varianten nur deshalb, weil verschiedene Pakete unterschiedliche Namen erwähnen. Wähle eine passende Variante, prüfe import cv2 und teste dann den Workflow, der tatsächlich blockiert.

Schweregrad

Mittel. OpenCV ist für viele Custom Nodes grundlegend, aber es muss in genau die Python-Umgebung installiert werden, die ComfyUI startet.

Vor dem Installieren: das richtige Python verwenden

Lösung

Schritt 1: Den aktuellen Zustand prüfen

Welche OpenCV-Pakete sind bereits installiert?

python -m pip list | findstr opencv

Für das offizielle Windows-Portable-Paket:

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

Wenn mehrere OpenCV-Pakete auftauchen, räume sie zuerst auf, bevor du eine Variante neu installierst.

Schritt 2: Bereinigen und sauber neu installieren

Fall 1: Noch gar kein OpenCV installiert

python -m pip install opencv-python-headless

Fall 2: OpenCV ist installiert, wirft aber Fehler, oder mehrere Varianten sind vorhanden

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

Fall 3: NumPy-Konflikt beim Import oder bei der Installation

Downgrade NumPy nicht als ersten Reflex global. Aktuelle ComfyUI-Umgebungen können legitim NumPy 2.x verwenden, während ältere Plugins noch 1.x erwarten.

Wenn das Log einen klaren NumPy-/OpenCV-Kompatibilitätsfehler nennt, wähle eine einzelne OpenCV-Version, die zum gewünschten NumPy-Stack passt, oder isoliere das ältere Plugin in eine separate Umgebung.

Fall 4: pip check sagt nur, dass ein anderes Paket OpenCV braucht

Wenn du nur eine pip check-Zeile siehst, prüfe zuerst, ob das Plugin überhaupt importiert und ob dein Workflow es wirklich verwendet. Eine fehlende OpenCV-Deklaration ist nicht automatisch ein fataler ComfyUI-Startfehler.

Wenn der Workflow blockiert ist, installiere eine OpenCV-Variante und teste:

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

Wenn ein Paket ausdrücklich Contrib-Module braucht, verwende opencv-contrib-python-headless statt es zusätzlich auf opencv-python-headless zu stapeln.

Schritt 3: Installation prüfen

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

Wenn eine Versionsnummer erscheint, starte ComfyUI neu und prüfe, ob das Plugin nun korrekt importiert.

Noch nicht gelöst?

Sammle dann:

• die Ausgabe von python -m pip list | findstr opencv
• die Ausgabe von python -m pip list | findstr numpy
• die vollständige IMPORT FAILED-Traceback-Meldung
• deinen Installationstyp: Portable, Desktop, manuelle venv oder verwalteter Launcher

Wenn du den schnellsten Reparaturpfad brauchst, nutze Expert Help.

Quellen

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