ModuleNotFoundError: No module named 'nunchaku' (ComfyUI) beheben

Wenn Sie nach ModuleNotFoundError: No module named 'nunchaku', No module named 'nunchaku.lora', No module named 'nunchaku.models', NunchakuFluxLoraLoader, NunchakuFluxLoraStack oder NunchakuFluxDiTLoader suchen, lautet die kurze Antwort:

Installieren Sie kein unbezogenes PyPI-Paket namens nunchaku. Überprüfen Sie zuerst, ob das Plugin ComfyUI-nunchaku erfolgreich importiert wurde, und installieren Sie dann das offizielle Nunchaku-Wheel-Paket, das mit Ihrem Python, PyTorch, CUDA und Ihrer GPU kompatibel ist.

Laut den Wonderful Launcher-Telemetriedaten vom 8. Juli 2026 führte der direkte Import von nunchaku in den letzten 30 Tagen bei 5 Installationsinstanzen zu 233 fatalen Fehlern. Submodul-Varianten wie nunchaku.lora, nunchaku.utils, nunchaku.merge_safetensors und nunchaku.models traten ebenfalls auf.

Präzise Fehlerprotokolle

Wenn in Ihrem Startprotokoll einer der folgenden Fehler auftritt, ist dieser Leitfaden für Sie gedacht:

ModuleNotFoundError: No module named 'nunchaku'
ModuleNotFoundError: No module named 'nunchaku.lora'
ModuleNotFoundError: No module named 'nunchaku.models'
Node import failed: NunchakuFluxLoraLoader

Symptome

Wenn ComfyUI startet oder einen Workflow ausführt, zeigt das Konsolenprotokoll:

ModuleNotFoundError: No module named 'nunchaku'

Oder:

ImportError: cannot import name 'SVDQW4A4Linear'

Bei Nunchaku-FLUX-Workflows können auch rote oder fehlende Nodes angezeigt werden, wie:

Node import failed: NunchakuFluxLoraLoader
Node import failed: NunchakuFluxLoraStack
Node import failed: NunchakuFluxDiTLoader

Diese Node-Namen sind sichtbare Symptome auf Workflow-Ebene. Die eigentliche Ursache ist meist, dass das Plugin ComfyUI-nunchaku sein Nunchaku-Backend nicht laden kann.

Was ist Nunchaku?

Nunchaku ist eine vom Nunchaku-Team entwickelte 4-Bit-Quantisierungs-Inferenz-Engine, die auf der SVDQuant-Methode basiert. In ComfyUI wird sie normalerweise über das Plugin ComfyUI-nunchaku verwendet, um quantisierte FLUX-, Qwen-Image-, SANA-, PixArt- und verwandte Modell-Workflows mit geringerer VRAM-Auslastung auf NVIDIA-GPUs auszuführen.

Was passiert, wenn Sie die Installation überspringen?

ComfyUI selbst benötigt kein Nunchaku, um normal zu funktionieren. Nunchaku ist nur in folgenden Fällen erforderlich:

• Ihr Workflow verwendet Nodes aus dem Plugin ComfyUI-nunchaku.
• Sie laden eine quantisierte SVDQuant/Nunchaku-Modelldatei.
• Der Workflow erfordert explizit Nunchaku-Loader- oder Sampler-Nodes.

Wenn Ihr Workflow diese Nodes oder quantisierten Modelle nicht verwendet, können Sie diesen Fehler ignorieren.

Einteilung der Fehler

Vermeiden Sie die PyPI-Namensfalle

Das fehlende Python-Modul heißt zwar nunchaku, aber das auf PyPI unter diesem Namen registrierte Paket ist ein unbezogenes wissenschaftliches Paket für stückweise lineare Segmentierung. Die Installation repariert ComfyUI Nunchaku nicht.

Die offizielle Nunchaku-Dokumentation empfiehlt, zuerst das ComfyUI-Plugin zu installieren und dann das Backend von der offiziellen Nunchaku-Quelle zu beziehen, oder den Workflow install_wheel.json von ComfyUI-nunchaku zu nutzen, falls verfügbar.

Systemvoraussetzungen

Nunchaku hat strenge Kompatibilitätseinschränkungen. Überprüfen Sie vor der Installation:

GPU-Anforderungen

Nunchaku ist hauptsächlich für NVIDIA-GPUs gedacht. Wenn Sie AMD, Intel, Apple Silicon oder reine CPU-Hardware nutzen, verwenden Sie andere Workflows wie GGUF-Quantisierungen oder kleinere Modelle.

CUDA- und PyTorch-Anforderungen

Das Nunchaku-Wheel ist eng mit Ihrer Laufzeitumgebung gekoppelt. Überprüfen Sie:

python --version
python -c "import torch; print(torch.__version__, torch.version.cuda)"

In der offiziellen Windows Portable-Version:

.\python_embeded\python.exe -s --version
.\python_embeded\python.exe -s -c "import torch; print(torch.__version__, torch.version.cuda)"

Wählen Sie ein Wheel, das exakt zu diesen Werten passt.

Installationsmethoden

Methode 1: Verwenden des ComfyUI-nunchaku Installer-Workflows

Wenn Sie die neueste Version des Plugins ComfyUI-nunchaku installiert haben, nutzen Sie dessen Workflow install_wheel.json (empfohlen):

1. Laden Sie den Workflow install_wheel.json in ComfyUI.
2. Führen Sie die Node im Modus update node aus, um verfügbare Versionen abzurufen.
3. Wählen Sie das Wheel aus, das zu Ihrem Python, PyTorch, CUDA und Ihrer GPU passt.
4. Führen Sie die Node im Modus install aus.
5. Starten Sie ComfyUI vollständig neu (ein Browser-Refresh reicht nicht aus).

Methode 2: Manuelle Installation eines passenden Wheels

Laden Sie das Wheel von der offiziellen Release-Quelle herunter:

• GitHub Releases: https://github.com/nunchaku-tech/nunchaku/releases
• Hugging Face organization: https://huggingface.co/nunchaku-tech

Installieren Sie es in der Python-Umgebung, in der ComfyUI ausgeführt wird:

python -m pip install <Pfad-oder-URL-zum-passenden-nunchaku-wheel.whl>

Unter Windows Portable:

.\python_embeded\python.exe -s -m pip install <Pfad-oder-URL-zum-passenden-nunchaku-wheel.whl>

Methode 3: Build aus den Quellen

Das Erstellen von Nunchaku unter Windows erfordert ein kompatibles CUDA Toolkit, Visual Studio/MSVC und eine vollständige Entwicklungsumgebung. Die Verwendung von vorkompilierten Wheels wird dringend empfohlen.

Typische Installationsfehler

"No matching distribution found"

Es gibt kein Wheel für Ihre Python/PyTorch/CUDA-Kombination. Überprüfen Sie Ihre Umgebung.

Falsches Paket installiert

Wenn Sie das unbezogene Paket namens nunchaku von PyPI installiert haben, deinstallieren Sie es vor der eigentlichen Installation:

python -m pip uninstall nunchaku -y

Installieren Sie danach das offizielle Nunchaku-Wheel.

Lokaler Verzeichniskonflikt

Wenn sich im aktuellen Arbeitsverzeichnis ein Ordner namens nunchaku befindet, lädt Python möglicherweise diesen Ordner anstelle des installierten Pakets. Stellen Sie sicher, dass keine namensgleichen Ordner im ComfyUI-Hauptverzeichnis oder im Plugin-Verzeichnis liegen.

Rote Nodes nach erfolgreichem Wheel-Import

Wenn import nunchaku erfolgreich ausgeführt wird, die Nodes aber weiterhin rot angezeigt werden, ist das Plugin beim Start fehlgeschlagen oder es liegt ein Abhängigkeitskonflikt vor. Prüfen Sie das Protokoll oder rufen Sie folgende URL auf:

http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk

Verifizierung der Installation

Überprüfen Sie den Import mit:

python -c "import nunchaku; print(getattr(nunchaku, '__version__', 'installed'))"

Starten Sie ComfyUI vollständig neu, um zu sehen, ob die Nodes geladen wurden.

Relevante Leitfäden

• ComfyUI No Module Named 'triton'
• ComfyUI-No-module-named-Fehler beheben
• ComfyUI-Abhängigkeitskonflikte
• GPU-Kompatibilität

Referenzen

• ComfyUI-nunchaku GitHub-Repository
• Nunchaku Installationsdokumentation
• Nunchaku GitHub-Releases