No module named 'insightface' in ComfyUI: Windows-Fix

Wenn ComfyUI No module named 'insightface' anzeigt, repariere die Python-Umgebung, mit der ComfyUI wirklich gestartet wird, nicht irgendein System-Python.

Unter Windows scheitert ein blindes pip install insightface oft, weil dabei nativer Code gebaut werden müsste. Der stabilere Weg ist ein passendes Wheel für deine Python-Version. ONNX Runtime brauchst du erst dann zusätzlich, wenn dein Face-Workflow es wirklich verwendet.

Symptome

Im Terminal von ComfyUI siehst du oft eine dieser Meldungen:

ModuleNotFoundError: No module named 'insightface'

oder:

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

Ursache

InsightFace ist eine Open-Source-Bibliothek für Gesichtserkennung und Gesichtsmerkmale. Mehrere ComfyUI-Plugins greifen darauf zurück:

• ReActor für Face Swap
• IPAdapter FaceID für Gesichtsmerkmals-Transfer
• InstantID für identitätstreue Generierung
• PuLID für gesichtsgeführte Generierung

Wenn InsightFace fehlt, laden genau diese Face-bezogenen Nodes nicht mehr. Der Rest von ComfyUI kann trotzdem normal weiterlaufen.

Warum Windows hier oft scheitert

Das Paket insightface auf PyPI wird als Source Distribution veröffentlicht. Unter Windows verlangt dieser Weg oft C++-Build-Tools, Python-Header und passende Build-Abhängigkeiten. Genau deshalb scheitert pip install insightface häufig mit Compiler-Fehlern.

Schweregrad

Mittel. Installiere InsightFace nur dann, wenn dein Workflow Face Swap, FaceID, InstantID, PuLID oder ein ähnliches Feature wirklich braucht.

Typische Installationsfehler

error: Microsoft Visual C++ 14.0 or greater is required.

Building wheel for insightface (pyproject.toml) ... error
ERROR: Failed building wheel for insightface

fatal error C1083: Cannot open include file: 'Python.h': No such file or directory

Diese Meldungen zeigen fast immer, dass du im falschen Installationspfad gelandet bist: lokaler Build statt fertigem Windows-Wheel.

Lösung

Schritt 1: Das richtige Python verwenden

Installiere immer in die Umgebung, mit der ComfyUI gestartet wird:

Prüfe zuerst die Python-Version:

python --version

Für die Portable-Version:

.\python_embeded\python.exe -s --version

Schritt 2: Ein passendes vorgebautes Wheel installieren

Unter Windows werden in der Praxis oft die Community-Wheels aus dem ReActor-Umfeld verwendet. Nimm das Wheel, das zu deiner Python-Version passt:

Für das offizielle Windows-Portable-Paket ersetze python -m pip durch:

.\python_embeded\python.exe -s -m pip

Das sind Community-Wheels, keine offiziellen PyPI-Dateien des Projekts InsightFace. Sie sind hier trotzdem sinnvoll, weil sie dir den lokalen C++-Build ersparen.

Schritt 3: ONNX Runtime nur bei Bedarf installieren

InsightFace verwendet ONNX Runtime als Inferenz-Backend. Für viele Workflows reicht CPU-ONNX-Runtime:

python -m pip install onnxruntime

Für NVIDIA-GPU-Beschleunigung:

python -m pip install onnxruntime-gpu

Wenn dabei Fehler mit onnxruntime_providers_cuda.dll auftauchen, prüfe zuerst den ONNX-/ONNXRuntime-Leitfaden, bevor du weitere Pakete änderst.

Schritt 4: NumPy nicht vorschnell downgraden

Downgrade NumPy nicht allein deshalb, weil irgendwo InsightFace genannt wird. Moderne ComfyUI-Umgebungen können legitim NumPy 2.x verwenden.

Ziehe ein NumPy-Downgrade nur dann in Betracht, wenn ein echter Kompatibilitätsfehler aus genau dem Face-Plugin kommt, das du brauchst:

python -m pip install "numpy<2"

Teste danach nur den betroffenen Face-Workflow. Nicht die ganze Umgebung auf Verdacht umbauen.

Schritt 5: ComfyUI neu starten

Wenn ein Plugin beim Start bereits fehlgeschlagen ist, registriert es seine Nodes erst nach dem nächsten vollständigen Neustart.

Installation prüfen

Führe im selben Python aus:

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

Beim Community-Wheel ist die erwartete Ausgabe oft 0.7.3.

Immer noch nicht gelöst?

Sammle dann:

• die vollständige IMPORT FAILED-Traceback-Meldung
• die Ausgabe von python --version
• die Ausgabe von python -c "import torch; print(torch.__version__, torch.version.cuda)"
• ob du CPU- oder GPU-ONNX-Runtime installiert hast

Wenn du den schnellsten Reparaturpfad brauchst, nutze Expert Help.

Quellen

• ComfyUI troubleshooting overview
• ComfyUI custom node troubleshooting guide
• ComfyUI model troubleshooting guide
• InsightFace GitHub repository