"ModuleNotFoundError: No module named 'nunchaku'"

Error message

When ComfyUI starts or runs a workflow, the terminal log shows:

ModuleNotFoundError: No module named 'nunchaku'

Or:

ImportError: cannot import name 'SVDQW4A4Linear'

What is Nunchaku

Nunchaku is a 4-bit quantized inference engine developed by MIT HAN Lab, based on the SVDQuant method (ICLR 2025 Spotlight). Its primary purpose is to run large diffusion models such as FLUX, SANA, and PixArt on GPUs with limited VRAM.

For example, FLUX.1-dev requires about 24 GB of VRAM at full precision, but with Nunchaku quantization this drops to 6-12 GB.

What happens if you skip the install

ComfyUI itself will run fine. Nunchaku is only needed when:

• Using nodes from the ComfyUI-nunchaku plugin (e.g. Nunchaku FLUX DiT Loader)
• Loading SVDQuant-quantized model files (from the nunchaku-ai organization on HuggingFace)
• Running workflows that depend on those nodes

If your workflow does not involve quantized models, you can safely ignore this error. If you have enough VRAM (24 GB or more), you can use full-precision models directly and skip Nunchaku entirely.

Hardware and software requirements

Nunchaku has strict compatibility constraints. Verify the following before installing:

GPU requirements

Only NVIDIA GPUs are supported, and only the following architectures:

Architecture	GPUs	Quantization format	Data type
Turing	RTX 20 series (2060/2070/2080)	INT4	float16
Ampere	RTX 30 series (3060/3070/3080/3090)	INT4	bfloat16
Ada Lovelace	RTX 40 series (4060/4070/4080/4090)	INT4	bfloat16
Blackwell	RTX 50 series (5070/5080/5090)	INT4 + FP4	bfloat16

Not supported: AMD GPUs, Intel GPUs, Apple Silicon, CPU-only environments.

CUDA version requirements

Platform	Minimum CUDA version	RTX 50 series
Windows	CUDA 12.6	CUDA 12.8
Linux	CUDA 12.2	CUDA 12.8

Check your CUDA version:

nvcc --version

Or check the CUDA version used by PyTorch:

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

PyTorch version requirements

• PyTorch 2.5 or later
• RTX 50 series requires PyTorch 2.7 or later

Python version requirements

• Python 3.10, 3.11, 3.12, 3.13

Installation methods

Method 1: pip install (recommended)

Run the following in the ComfyLauncher environment terminal:

pip install nunchaku-ai

Important: The nunchaku package on PyPI (without the -ai suffix) is an unrelated package. Installing it will not fix this error. You must install nunchaku-ai.

Restart ComfyUI after installation.

Verify the installation:

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

Method 2: Install via ComfyUI node

If you already have the ComfyUI-nunchaku plugin installed (v0.3.2 or later):

1. Load the install_wheel.json workflow in ComfyUI
2. Find the NunchakuWheelInstaller node
3. Set the mode to update node and run it to fetch available versions
4. Refresh the browser, select a version, set the mode to install, and run it
5. Fully restart ComfyUI

Method 3: Manual wheel download

If pip install fails or your network is restricted, you can manually download the appropriate wheel file.

Wheel file naming format:

nunchaku-{version}+cu{CUDA version}torch{PyTorch version}-cp{Python version}-{platform}.whl

Download sources:

• GitHub Releases: https://github.com/nunchaku-ai/nunchaku/releases
• HuggingFace: https://huggingface.co/nunchaku-ai
• ModelScope (recommended for users in China): https://modelscope.cn/organizations/nunchaku-tech

Install after downloading:

pip install nunchaku-{wheel filename matching your environment}.whl

Common installation failures

"No matching distribution found"

Your Python/PyTorch/CUDA version combination does not have a prebuilt wheel. Check:

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

Make sure PyTorch is 2.5 or later and CUDA is 12.6 or later (on Windows).

CUDA version too old

Windows users need CUDA 12.6 or later. If your CUDA version is older, upgrade the CUDA Toolkit and GPU driver first.

Wrong package installed

pip install nunchaku     # Wrong - this is an unrelated package
pip install nunchaku-ai  # Correct

Local directory conflict

If there is a folder named nunchaku in the current working directory, Python will load that folder instead of the installed package. Make sure there is no conflicting folder under the ComfyUI directory.

RTX 20 series special configuration

The Turing architecture (RTX 20 series) does not support bfloat16 or flash-attention2. When using these GPUs, configure the node as follows:

• Set attention to nunchaku-fp16
• Set data_type to float16

VRAM optimization when running out of memory

If Nunchaku is installed but you run out of VRAM at runtime, try the following:

Optimization	VRAM saved
Enable CPU offload (set to auto)	~4-6 GB
Use 4-bit T5 encoder (nunchaku-ai/nunchaku-t5)	~3-4 GB
Disable cache (cache_threshold=999)	~1-2 GB

Alternatives

If your hardware does not meet Nunchaku's requirements (e.g. no NVIDIA GPU or CUDA version too old), consider:

• Full-precision models: If you have enough VRAM (24 GB or more), use the full FLUX.1-dev model without quantization
• GGUF quantization: Some ComfyUI nodes support GGUF-format quantized models, which have more relaxed hardware requirements
• Smaller models: Switch to SDXL or SD 1.5, which can run on 8 GB of VRAM without quantization
• Cloud services: If local hardware is limited, consider running ComfyUI on a cloud GPU

Still not resolved?

If you still have issues after following the steps above, contact support through the "Contact Us" button in the app and include the following:

• Full terminal error log
• Output of python --version
• Output of python -c "import torch; print(torch.__version__, torch.version.cuda)"
• Your GPU model