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 / Nunchaku 量化後的模型文件
• 運行依賴上述節點的工作流

如果你的工作流不涉及量化模型，可以忽略這個錯誤。如果你的顯存足夠（24GB 以上），也可以直接使用全精度模型，完全不需要 Nunchaku。

硬件和軟件要求

Nunchaku 有嚴格的兼容性限制，安裝前請確認：

顯卡、CUDA、PyTorch 與 Python 的相容性

Nunchaku 主要面向 NVIDIA GPU。官方支援範圍會隨 GPU 架構、CUDA、PyTorch 與 wheel 的可用性改變；若你使用 AMD、Intel、Apple Silicon 或純 CPU，請優先選擇 GGUF、較小模型或其他相容的工作流。

安裝前先用 ComfyUI 實際啟動的 Python 檢查環境：

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）、PyTorch 版本、CUDA 版本、Windows 架構，以及官方文件有要求時的 GPU 世代。不要只因為看到某個版本號，就升級 CUDA Toolkit 或替換整個 Torch 堆疊。

安裝方法

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

不要執行 pip install nunchaku，也不要假定任何名稱相近的 PyPI 套件可修復 ComfyUI Nunchaku。nunchaku 這個 PyPI 名稱是無關套件；正確路徑是使用官方 Nunchaku wheel 或 ComfyUI-nunchaku 的安裝工作流，並讓 wheel 與目前的 Python、PyTorch、CUDA 和 GPU 相符。

方法二：通過 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-tech/nunchaku/releases
• Hugging Face: https://huggingface.co/nunchaku-tech
• ModelScope（國內用戶推薦）: https://modelscope.cn/organizations/nunchaku-tech

下載後安裝：

python -m pip install <與目前環境相符的 nunchaku wheel 檔案>

常見安裝失敗原因

"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     # 錯誤：這是一個無關的 PyPI 套件
python -m pip install <與目前環境相符的官方 nunchaku wheel>

本地目錄衝突

如果當前工作目錄下有名為 nunchaku 的文件夾，Python 會優先加載該文件夾而不是已安裝的庫。確保 ComfyUI 目錄下沒有同名文件夾衝突。

RTX 20 系列特殊配置

Turing 架構（RTX 20 系列）不支持 bfloat16 和 flash-attention2。使用時需要在節點中配置：

• attention 設為 nunchaku-fp16
• data_type 設為 float16

顯存不足時的優化

如果安裝成功但運行時顯存不足，可以嘗試：

替代方案

如果你的硬件不滿足 Nunchaku 的要求（例如沒有 NVIDIA 顯卡或 CUDA 版本過低），可以考慮：

• 使用全精度模型： 如果顯存足夠，直接使用完整模型，不需要量化
• 使用 GGUF 量化： 部分 ComfyUI 節點支持 GGUF 格式的量化模型，對硬件要求更寬鬆
• 使用更小的模型： 改用 SDXL 或 SD 1.5 等較小的模型，不需要量化即可在 8GB 顯存上運行
• 使用雲端服務： 如果本地硬件受限，可以考慮使用雲端 GPU 運行 ComfyUI

仍然無法解決？

如果按照上述步驟操作後仍有問題，請通過應用內的「聯繫我們」按鈕聯繫技術支持，並提供以下信息：

• 完整的終端錯誤日誌
• python --version 的輸出
• python -c "import torch; print(torch.__version__, torch.version.cuda)" 的輸出
• 你的顯卡型號