ModuleNotFoundError: No module named 'nunchaku'（ComfyUI 中缺少 nunchaku 模块）

如果你搜索到 ModuleNotFoundError: No module named 'nunchaku'、No module named 'nunchaku.lora'、No module named 'nunchaku.models'、NunchakuFluxLoraLoader、NunchakuFluxLoraStack 或 NunchakuFluxDiTLoader，简短的答案是：

不要安装 PyPI 上名为 nunchaku 的无关包。请先确认 ComfyUI-nunchaku 插件是否已成功导入，然后安装与你的 Python、PyTorch、CUDA 和 GPU 相匹配的官方 Nunchaku wheel 包。

nunchaku、nunchaku.lora、nunchaku.utils、nunchaku.merge_safetensors 和 nunchaku.models 都可能指向同一类问题：插件已尝试使用 Nunchaku 后端，但后端 wheel、Python、PyTorch、CUDA、GPU 架构或插件版本不匹配。不要给所有机器套同一条通用安装命令。

精确错误日志

如果你的终端或启动日志中出现以下任意错误信息，本指南正是为你准备的：

ModuleNotFoundError: No module named 'nunchaku'
ModuleNotFoundError: No module named 'nunchaku.lora'
ModuleNotFoundError: No module named 'nunchaku.models'
Node import failed: NunchakuFluxLoraLoader

错误信息

当 ComfyUI 启动或运行工作流时，终端日志显示：

ModuleNotFoundError: No module named 'nunchaku'

或：

ImportError: cannot import name 'SVDQW4A4Linear'

Nunchaku FLUX 工作流还可能出现红色或缺失的节点，例如：

Node import failed: NunchakuFluxLoraLoader
Node import failed: NunchakuFluxLoraStack
Node import failed: NunchakuFluxDiTLoader

这些节点名称是工作流层面的可见症状。根本原因通常是 ComfyUI-nunchaku 插件无法加载其 Nunchaku 后端。

Nunchaku 是什么

Nunchaku 是由 Nunchaku 团队围绕 SVDQuant 方法开发的 4 位量化推理引擎。在 ComfyUI 中，它通常通过 ComfyUI-nunchaku 插件使用，以便在 NVIDIA GPU 上以较低显存占用运行量化的 FLUX、Qwen-Image、SANA、PixArt 及相关模型工作流。

跳过安装会发生什么

ComfyUI 本身无需 Nunchaku 也可正常运行。 仅在以下情况下才需要 Nunchaku：

• 你的工作流使用了 ComfyUI-nunchaku 插件中的节点
• 你加载了 SVDQuant/Nunchaku 量化模型文件
• 工作流明确要求 Nunchaku 加载器或采样器节点

如果你的工作流不涉及这些节点或量化模型，可以忽略此错误，无需引入沉重的原生依赖。

你遇到的是哪种 Nunchaku 错误？

如果工作流只显示红色节点名称，不要搜索以节点类名命名的包。先修复插件导入和后端 wheel 问题。

先确认边界

Nunchaku 错误的覆盖范围不如 Triton 或 SageAttention 广，但风险更高，因为后端 wheel 与 Python、PyTorch、CUDA、GPU 架构和插件版本紧密绑定。

首先：避免 PyPI 包名陷阱

缺失的 Python 模块名为 nunchaku，但 PyPI 上名为 nunchaku 的公开包是一个用于分段线性分割的无关科学计算包。安装它无法修复 ComfyUI Nunchaku 工作流。

Nunchaku 官方文档建议先安装 ComfyUI 插件，然后从官方 Nunchaku 发布源安装后端，或在可用时使用 ComfyUI-nunchaku 的 install_wheel.json 工作流。

使用以下输入边界参考：

硬件和软件要求

Nunchaku 有严格的兼容性限制。安装前请验证以下内容：

GPU 要求

Nunchaku 主要面向 NVIDIA GPU。官方文档按 GPU 架构、CUDA、PyTorch 和 wheel 可用性列出了支持情况。如果你使用的是 AMD、Intel、Apple Silicon 或纯 CPU 硬件，请使用不同的工作流路径，例如 GGUF 量化或更小的模型。

CUDA 和 PyTorch 要求

Nunchaku wheel 与你的环境紧密绑定。请检查：

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

在官方 Windows 便携包中，从便携包根目录运行：

.\python_embeded\python.exe -s --version
.\python_embeded\python.exe -s -c "import torch; print(torch.__version__, torch.version.cuda)"

将 wheel 与以下内容匹配：

• Python 标签，例如 cp311 或 cp312
• PyTorch 版本
• CUDA 版本
• Windows 架构
• 当 wheel 或文档提及时，还需匹配 GPU 世代

安装方法

方法一：使用 ComfyUI-nunchaku 安装器工作流

如果你已安装了最新版 ComfyUI-nunchaku 插件，请使用其 install_wheel.json 工作流。官方安装文档将此描述为在 ComfyUI 中安装或更新后端 wheel 的推荐路径：

1. 在 ComfyUI 中加载 install_wheel.json 工作流。
2. 以 update node 模式运行安装器节点以获取可用版本。
3. 选择与你的 Python、PyTorch、CUDA 和 GPU 匹配的 wheel。
4. 以 install 模式运行节点。
5. 完全重启 ComfyUI。

此方法最安全，因为插件可以为当前活跃环境引导 wheel 的选择。

安装完成后，请完全重启 ComfyUI。仅刷新浏览器是不够的，因为自定义节点是在后端启动期间注册的。

方法二：手动安装匹配的 wheel

从 Nunchaku 官方发布源下载 wheel。官方文档目前链接了以下来源，GitHub 可能在项目组织名称之间发生重定向：

• GitHub Releases：https://github.com/nunchaku-tech/nunchaku/releases
• Hugging Face 组织：https://huggingface.co/nunchaku-tech
• ModelScope 组织：https://modelscope.cn/organization/nunchaku-tech

然后使用启动 ComfyUI 的 Python 安装它：

python -m pip install <path-or-url-to-matching-nunchaku-wheel.whl>

对于官方 Windows 便携包：

.\python_embeded\python.exe -s -m pip install <path-or-url-to-matching-nunchaku-wheel.whl>

不要盲目复制示例 wheel URL。为 Python 3.11 和 PyTorch 2.7 构建的 wheel 无法修复 Python 3.12 / 不同 PyTorch 版本的环境。

方法三：仅在确有必要时从源码构建

在 Windows 上构建 Nunchaku 需要兼容的 CUDA 工具包、Visual Studio/MSVC 以及正确的开发环境。对于大多数 ComfyUI 用户来说，预构建的 wheel 或安装器工作流是实用的选择。

常见安装失败

"No matching distribution found"

你的 Python/PyTorch/CUDA 组合在你所用的源中没有匹配的 wheel。请检查：

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

然后选择为该精确组合构建的 wheel，或在安装 Nunchaku 之前调整基础环境。

安装了错误的包

如果你已安装了 PyPI 上名为 nunchaku 的无关包，它不会修复 ComfyUI Nunchaku。在安装正确的 wheel 之前，请先卸载它：

python -m pip uninstall nunchaku -y

然后使用官方 Nunchaku wheel/安装工作流。

本地目录冲突

如果当前工作目录中存在名为 nunchaku 的文件夹，Python 可能会加载该文件夹而不是已安装的包。确保 ComfyUI 根目录或插件文件夹下没有冲突的文件夹。

wheel 导入成功后节点仍显示红色

如果 import nunchaku 正常运行，但 NunchakuFluxLoraLoader、NunchakuFluxLoraStack 或 NunchakuFluxDiTLoader 仍然缺失，可能是后端已安装，而自定义节点插件在启动时已过时或失败。

检查：

http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk

然后在响应或启动日志中查找 ComfyUI-nunchaku。如果另一个依赖冲突在节点注册之前阻止了插件，请先修复最早的导入失败。更宏观的依赖冲突指南解释了如何在修复一个插件的同时避免破坏 Torch、NumPy、OpenCV 或 Transformers。

RTX 20 系列特殊配置

较旧的 Turing GPU 在数据类型/注意力机制方面与较新的 Ada 或 Blackwell GPU 有不同的限制。请遵循 Nunchaku 文档中针对你的 GPU 世代的精确节点设置，而不是复制来自 40 系列或 50 系列工作流的设置。

验证安装

运行：

python -c "import nunchaku; print(getattr(nunchaku, '__version__', 'installed'))"

然后完全重启 ComfyUI，检查 ComfyUI-nunchaku 节点是否已注册。

替代方案

如果你的硬件不满足 Nunchaku 的要求，请考虑：

• 全精度模型： 如果你有足够的显存
• GGUF 量化： 通常更容易在更多配置上运行
• 更小的模型： SDXL 或 SD 1.5 工作流可以在较少显存上运行
• 云端 GPU： 当本地硬件不适合时

仍未解决？

如果你仍然遇到问题，请收集以下信息：

• 完整的终端错误日志
• python --version 的输出
• python -c "import torch; print(torch.__version__, torch.version.cuda)" 的输出
• 你的 GPU 型号
• 确切的 wheel 文件名或安装器工作流输出

保存这些详细信息和工作流，再根据节点作者的文档、wheel 来源和你的 Python/Torch/CUDA 版本继续排查。

来源参考

• ComfyUI-nunchaku GitHub 仓库
• ComfyUI-nunchaku 安装文档
• Nunchaku 安装文档
• Nunchaku 常见问题：错误的 PyPI 包
• Nunchaku 在 Hugging Face 上的 wheel 仓库
• Nunchaku GitHub 发布页面
• ComfyUI 自定义节点故障排除指南