高频错误
"ModuleNotFoundError: No module named 'nunchaku'"
ComfyUI 中缺少 Nunchaku 4-bit 量化推理引擎的排查与安装指南。
错误信息
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-fp16data_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)"的输出- 你的显卡型号
Wonderful Launcher 文档