ModuleNotFoundError: No module named 'nunchaku'（ComfyUI）の修復

コンソールまたは起動ログに 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 パッケージを導入します。

2026年7月8日時点の Wonderful Launcher テレメトリデータによると、nunchaku インポートの失敗は過去 30日間に 5つのインストールインスタンスで 233回の致命的なエラーを引き起こしました。nunchaku.lora、nunchaku.utils、nunchaku.merge_safetensors、および nunchaku.models といったサブモジュールのバリエーションも同様のエラーが発生しています。

精確なエラーログ

コンソールまたは起動ログに以下のいずれかのエラーが出ている場合、本ガイドの対象となります：

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 メソッドに基づく 4bit 量子化推論エンジンです。ComfyUI では、通常 ComfyUI-nunchaku 拡張機能を通じて使用され、NVIDIA GPU 上で低 VRAM で量子化された FLUX、Qwen-Image、SANA、PixArt などのモデルワークフローを実行するために使用されます。

インストールを見送る場合の影響

ComfyUI 自体は Nunchaku なしでも正常に動作します。 以下の条件に該当する場合のみ Nunchaku が必要になります：

• ワークフローで ComfyUI-nunchaku 拡張機能のノードを使用している場合
• SVDQuant/Nunchaku 量子化モデルファイルをロードする場合
• ワークフローが明示的に Nunchaku ロードまたはサンプラーノードを要求している場合

これらに該当しない場合は、このエラーは無視して構いません。

エラーパターンの分類

PyPI パッケージ名トラップの回避

不足している Python モジュール名は nunchaku ですが、PyPI に登録されている標準の nunchaku パッケージは、区分線形分割に使用される無関係な学術計算用パッケージです。これをインストールしても ComfyUI Nunchaku は動作しません。

Nunchaku の公式ドキュメントでは、まず ComfyUI 拡張機能をインストールし、その後に公式の Nunchaku リリース元からバックエンドを導入するか、または ComfyUI-nunchaku の install_wheel.json ワークフローを使用することを推奨しています。

ハードウェアおよびソフトウェア要件

Nunchaku には厳格な互換性制限があります。導入前に以下を確認してください：

GPU 要件

Nunchaku は主に NVIDIA GPU を対象としています。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 ファイルを選択します。

インストール手順

方法 1：ComfyUI-nunchaku インストーラーワークフローを使用する

最新の ComfyUI-nunchaku プラグインをインストールしている場合、その中の install_wheel.json ワークフローを使用するのが最も推奨されます：

1. ComfyUI に install_wheel.json ワークフローをロードします。
2. インストーラーノードを update node モードで実行し、利用可能なバージョンを取得します。
3. 使用中の Python、PyTorch、CUDA、および GPU に適合する wheel を選択します。
4. ノードを install モードで実行します。
5. ComfyUI を完全に再起動します（ブラウザの更新だけでは不十分です）。

方法 2：適合する wheel を手動インストールする

公式のリリース元から wheel をダウンロードします：

• GitHub Releases：https://github.com/nunchaku-tech/nunchaku/releases
• Hugging Face organization：https://huggingface.co/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>

方法 3：ソースからビルドする

Windows 環境での Nunchaku のビル드には、CUDA ツールキット、Visual Studio/MSVC、および適切な開発環境が必要です。基本的にはビルド済み wheel の使用を強く推奨します。

典型的なエラーと解決策

"No matching distribution found"

使用している Python/PyTorch/CUDA の組み合わせに適合する wheel がリリースされていません。環境の確認を行ってください。

誤ったパッケージのインストール

PyPI から標準の nunchaku パッケージを入れてしまった場合は、事前にアンインストールします：

python -m pip uninstall nunchaku -y

その上で公式の Nunchaku wheel を再インストールします。

ローカルディレクトリの衝突

カレントディレクトリに nunchaku という名前のフォルダが存在する場合、Python はパッケージではなくそのフォルダを読み込んでしまいます。ComfyUI ルートやプラグインディレクトリに名前が衝突するフォルダがないか確認してください。

導入後にノードが赤色のままの場合

import nunchaku は成功するものの、ノードが未登録のままの場合、拡張機能プラグイン自体のロードが失敗しているか、他の依存関係が衝突しています。起動ログまたは以下のエンドポイントを確認してください：

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

インストールの検証

以下を実行して確認します：

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

その後、ComfyUI を完全に再起動し、ノードがロードされているか確認します。

関連ガイド

• ComfyUI No Module Named 'triton'
• 修復 ComfyUI 中的 No module named 錯誤
• ComfyUI 依賴衝突
• GPU 兼容性

参照元

• ComfyUI-nunchaku GitHub リポジトリ
• Nunchaku 公式ドキュメント
• Nunchaku GitHub リリース