Nunchaku still fails after installation: align the node, wheel and model

Treat these as separate components

The Nunchaku backend wheel, ComfyUI-nunchaku plugin and quantized model files are separate. An installation success for one component does not prove that another can import, load or run. Check the exact release documentation for each component and the Python executable printed by the running ComfyUI instance. Backend installation Plugin installation

python -m pip show nunchaku torch
python -c "import sys, platform; print(sys.executable, sys.version); print(platform.system(), platform.machine())"
python -m pip debug

Run these with ComfyUI's actual Python, not merely the default shell interpreter. They report environment information; they do not test the native extension, GPU or model.

Read a wheel name correctly

The official example nunchaku-0.3.1+torch2.7-cp311-cp311-linux_x86_64.whl is an example, not a universal install URL. Standard wheel compatibility tags are the final Python, ABI and platform fields (here cp311-cp311-linux_x86_64). +torch2.7 is in the distribution version; compare it with the publisher's Torch build instructions separately. A wheel accepted by pip can still fail when its native extension loads. Do not rename an incompatible file to bypass pip's tag check. Nunchaku installation Wheel specification pip debug

Separate failures by stage

1. Install or import: Record the failing interpreter, full pip/import error and selected wheel. If the plugin loads but reports No module named nunchaku, check whether the backend was installed into ComfyUI's bundled Python. A pip wheel rejection points to the standard tags; a native-library load error requires its own traceback plus Torch/CUDA/platform details.

2. Plugin and backend: Record both versions or commits and compare their own installation guidance. The plugin's install page explicitly installs the plugin first and backend second; the bundled wheel-install workflow is available only from its documented plugin version. An arbitrary wheel or wholesale Torch upgrade is not a substitute for a supported combination.

3. Model and hardware: Once import and node registration work, use an upstream workflow with the intended quantized model family and required companion files. The upstream usage guide distinguishes its model files and recommends FP4 for Blackwell versus INT4 for other supported GPUs; check the documentation for the selected release and hardware rather than treating these as a universal performance promise. A model-file or shape failure is later than wheel compatibility. Plugin usage

Completion check and limits

In an environment copy, confirm the same ComfyUI interpreter installs and imports the backend, the expected node registers, an intended quantized model loads, and a minimal upstream workflow generates. Record each result separately. No Nunchaku package, wheel, model or GPU was installed or run by this site; no speed or hardware compatibility is claimed.

Original sources

• Nunchaku backend installation — checked 2026-09-26.
• ComfyUI-nunchaku plugin installation — checked 2026-09-26.
• ComfyUI-nunchaku usage and model setup — checked 2026-09-26.
• Python wheel filename specification — checked 2026-09-26.
• pip debug reference — checked 2026-09-26.

Source and English-language review: 2026-09-26. Documentation versions and release assets may change; inspect the chosen versions before acting.

Related checks

• llama_cpp failures: distinguish installation, native builds and model loading
• Keep a reproducible ComfyUI repair record without exposing secrets