"ModuleNotFoundError: No module named 'nunchaku'" | Wonderful Launcher

错误信息

ComfyUI 启动或执行工作流时，终端日志中出现：

ModuleNotFoundError: No module named 'nunchaku'

或者：

ImportError: cannot import name 'SVDQW4A4Linear'

什么是 Nunchaku

Nunchaku 是 MIT HAN Lab 开发的 4-bit 量化推理引擎，基于 SVDQuant 方法（ICLR 2025 Spotlight）。它的核心用途是让 FLUX、SANA、PixArt 等大型扩散模型在显存有限的显卡上运行。

例如，FLUX.1-dev 全精度需要约 24GB 显存，使用 Nunchaku 量化后可降至 6-12GB。

不安装会怎样

ComfyUI 本身可以正常运行。 Nunchaku 只在以下场景需要：

使用 ComfyUI-nunchaku 插件的节点（如 Nunchaku FLUX DiT Loader）
加载 SVDQuant 量化后的模型文件（来自 HuggingFace nunchaku-ai 组织的模型）
运行依赖上述节点的工作流

如果你的工作流不涉及量化模型，可以忽略这个错误。如果你的显存足够（24GB 以上），也可以直接使用全精度模型，完全不需要 Nunchaku。

硬件和软件要求

Nunchaku 有严格的兼容性限制，安装前请确认：

显卡要求

仅支持 NVIDIA 显卡，且必须是以下架构：

架构	对应显卡	量化格式	数据类型
Turing	RTX 20 系列（2060/2070/2080）	INT4	float16
Ampere	RTX 30 系列（3060/3070/3080/3090）	INT4	bfloat16
Ada Lovelace	RTX 40 系列（4060/4070/4080/4090）	INT4	bfloat16
Blackwell	RTX 50 系列（5070/5080/5090）	INT4 + FP4	bfloat16

不支持： AMD 显卡、Intel 显卡、Apple Silicon、纯 CPU 环境。

CUDA 版本要求

平台	最低 CUDA 版本	RTX 50 系列
Windows	CUDA 12.6	CUDA 12.8
Linux	CUDA 12.2	CUDA 12.8

检查你的 CUDA 版本：

nvcc --version

或在 Python 中检查 PyTorch 使用的 CUDA：

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

PyTorch 版本要求

PyTorch 2.5 或更高版本
RTX 50 系列需要 PyTorch 2.7 或更高版本

Python 版本要求

Python 3.10、3.11、3.12、3.13

安装方法

方法一：pip install（推荐）

在 ComfyLauncher 的环境终端中执行：

pip install nunchaku-ai

注意： PyPI 上的 nunchaku（没有 -ai 后缀）是一个无关的包，安装它不会解决问题。必须安装 nunchaku-ai。

安装完成后重启 ComfyUI。

验证安装是否成功：

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

方法二：通过 ComfyUI 节点安装

如果你已经安装了 ComfyUI-nunchaku 插件（v0.3.2 或更新版本）：

在 ComfyUI 中加载 install_wheel.json 工作流
找到 NunchakuWheelInstaller 节点
将模式设为 update node 并执行，获取可用版本列表
刷新浏览器，选择版本，将模式设为 install 并执行
完全重启 ComfyUI

方法三：手动下载 wheel 文件

如果 pip install 失败或网络受限，可以手动下载对应的 wheel 文件。

wheel 文件命名格式：

nunchaku-{版本}+cu{CUDA版本}torch{PyTorch版本}-cp{Python版本}-{平台}.whl

下载源：

GitHub Releases: https://github.com/nunchaku-ai/nunchaku/releases
HuggingFace: https://huggingface.co/nunchaku-ai
ModelScope（国内用户推荐）: https://modelscope.cn/organizations/nunchaku-tech

下载后安装：

pip install nunchaku-{对应你环境的wheel文件名}.whl

常见安装失败原因

"No matching distribution found"

你的 Python/PyTorch/CUDA 版本组合没有对应的预编译 wheel。检查：

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

确保 PyTorch 版本在 2.5 以上，CUDA 版本在 12.6 以上（Windows）。

CUDA 版本过低

Windows 用户需要 CUDA 12.6 或更高版本。如果你的 CUDA 版本较低，需要先升级 CUDA Toolkit 和显卡驱动。

安装了错误的包

pip install nunchaku     # 错误 - 这是一个无关的包
pip install nunchaku-ai  # 正确

本地目录冲突

如果当前工作目录下有名为 nunchaku 的文件夹，Python 会优先加载该文件夹而不是已安装的库。确保 ComfyUI 目录下没有同名文件夹冲突。

RTX 20 系列特殊配置

Turing 架构（RTX 20 系列）不支持 bfloat16 和 flash-attention2。使用时需要在节点中配置：

attention 设为 nunchaku-fp16
data_type 设为 float16

显存不足时的优化

如果安装成功但运行时显存不足，可以尝试：

优化措施	节省显存
启用 CPU offload（设为 `auto`）	约 4-6 GB
使用 4-bit T5 编码器（`nunchaku-ai/nunchaku-t5`）	约 3-4 GB
禁用缓存（`cache_threshold=999`）	约 1-2 GB

替代方案

如果你的硬件不满足 Nunchaku 的要求（例如没有 NVIDIA 显卡或 CUDA 版本过低），可以考虑：

使用全精度模型： 如果显存足够（24GB 以上），直接使用 FLUX.1-dev 的完整模型，不需要量化
使用 GGUF 量化： 部分 ComfyUI 节点支持 GGUF 格式的量化模型，对硬件要求更宽松
使用更小的模型： 改用 SDXL 或 SD 1.5 等较小的模型，不需要量化即可在 8GB 显存上运行
使用云端服务： 如果本地硬件受限，可以考虑使用云端 GPU 运行 ComfyUI

仍然无法解决？

如果按照上述步骤操作后仍有问题，请通过应用内的「联系我们」按钮联系技术支持，并提供以下信息：

完整的终端错误日志
python --version 的输出
python -c "import torch; print(torch.__version__, torch.version.cuda)" 的输出
你的显卡型号