ModuleNotFoundError: No module named 'nunchaku'

错误信息

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 显卡，且必须是以下架构：

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

CUDA 版本要求

检查你的 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 或更新版本）：

1. 在 ComfyUI 中加载 install_wheel.json 工作流
2. 找到 NunchakuWheelInstaller 节点
3. 将模式设为 update node 并执行，获取可用版本列表
4. 刷新浏览器，选择版本，将模式设为 install 并执行
5. 完全重启 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

显存不足时的优化

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

替代方案

如果你的硬件不满足 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)" 的输出
• 你的显卡型号