How to Run Nunchaku Z-Image-Turbo on ComfyUI (Windows Portable Edition)

This article explains how to run Nunchaku Z-Image-Turbo on ComfyUI Windows Portable Edition.

⚠️ The most important Notice ⚠️

Dec 28, 2025, the official Nunchaku ComfyUI plugin released.

⚠️ Important Notice
Before starting this procedure, it is strongly recommended to make a full backup of your entire ComfyUI folder.

This guide is written specifically for the ComfyUI Windows Portable version. If you are using a non-portable setup (venv / system Python), paths and commands may differ.

As of December 27, 2025, the official Nunchaku ComfyUI plugin does NOT yet support Z-Image-Turbo,so an unofficial loader is required.

Prerequisites

OS: Windows
ComfyUI: Windows Portable Edition
Python / PyTorch: Bundled with ComfyUI Portable
Git: Installed (required for cloning custom nodes)

1. Check Your ComfyUI Environment

First, confirm which Python and PyTorch versions your ComfyUI Portable uses.

Launch ComfyUI
Open Settings
Check:
- Python version
- PyTorch version

Write these down carefully. After confirming, close ComfyUI.

For Portable Edition, it’s safer to install packages while ComfyUI is not running.

2. Install Nunchaku v1.1.0

2-1. Download the Correct `.whl` File

Go to the official Nunchaku releases page:

👉 https://github.com/nunchaku-tech/nunchaku/releases

Download the .whl file that matches all of the following:

Your Python version
Your PyTorch version
Windows OS

2-2. Install Using Portable Python

Copy the downloaded .whl file into your ComfyUI_windows_portable directory.

Open Command Prompt in that directory and run:

.\python_embeded\python.exe -m pip install XXX

Replace XXX with the actual filename.

Example:

.\python_embeded\python.exe -m pip install nunchaku-1.1.0+cu121-cp310-win_amd64.whl

3. Update diffusers to Version 0.36.0

Z-Image-Turbo requires a specific diffusers version for compatibility.

Run the following command using the Portable Python:

.\python_embeded\python.exe -m pip install --upgrade diffusers==0.36.0

Using other diffusers versions may cause missing nodes or runtime errors.

4. Install the Unofficial Z-Image-Turbo Loader

Since the official Nunchaku ComfyUI plugin does not yet support Z-Image-Turbo, we use an unofficial loader.

4-1. Move to `custom_nodes`

cd ComfyUI_windows_portable\ComfyUI\custom_nodes

4-2. Clone the Repository

git clone https://github.com/ussoewwin/ComfyUI-nunchaku-unofficial-z-image-turbo-loader

This step will likely become unnecessary once the official plugin adds support.

(Not available as of 2025-12-27)

5. Launch ComfyUI and Build the Workflow

After completing the steps above, launch ComfyUI.

Workflow Setup

Start with a Nunchaku-Qwen-Image workflow and make the following change:

Replace:
- Nunchaku-Qwen-Image DiT Loader
With:
- Nunchaku-ussoewwin Z-Image-Turbo DiT Loader

Select Appropriate Components

Model: Z-Image-Turbo compatible DiT
CLIP: Matching CLIP model
VAE: Compatible VAE

With this setup, Z-Image-Turbo should run successfully.

I share my workflow JSON as a reference.

(It's a re-use of a previous workflow, so it's not a very good one...)

Summary

This guide is Portable Edition only
Key versions:
- Nunchaku v1.1.0
- diffusers 0.36.0
Z-Image-Turbo currently requires an unofficial loader
Official support may remove this requirement in the future

Hopefully this helps others get Z-Image-Turbo running smoothly on ComfyUI.

ComfyUI（Portable版）で Nunchaku Z-Image-Turbo を動かす手順まとめ

この記事では ComfyUI Windows Portable版 を使ってNunchaku Z-Image-Turbo を動かすまでの手順をまとめます。

⚠️ 最も重要なお知らせ ⚠️

2025年12月28日に、公式Nunchaku ComfyUI Pluginがリリースされました。

⚠️ 重要な注意事項
本手順を実行する前に、ComfyUI フォルダ全体のバックアップを取っておくことを強く推奨します。

本記事は ComfyUI Windows Portable版 を前提にしています。
通常版（venv / system Python）ではパスや手順が異なる場合があります。

2025/12/27 時点では、Z-Image-Turbo対応の公式 Nunchaku ComfyUI Plugin は未リリースのため、アンオフィシャルローダーを使用します。

前提環境

OS：Windows
ComfyUI：Windows Portable版
Python / PyTorch：ComfyUIに同梱されているものを使用
Git：インストール済み（custom_nodes を clone するため）

1. ComfyUI の設定を確認する

まず 自分の ComfyUI が使っている Python / PyTorch のバージョンを確認します。

ComfyUI を起動
設定（Settings）画面を開く
Python バージョン
PyTorch バージョン

を必ずメモしてください。

確認できたら ComfyUI を終了します。
（Portable版では起動中に pip install しない方が安全です）

2. Nunchaku v1.1.0 をインストールする

2-1. whl ファイルをダウンロード

以下のリリースページから、自分の環境と一致する whl ファイルを選んでダウンロードします。

Python バージョン
PyTorch バージョン
OS（Windows）

👉 https://github.com/nunchaku-tech/nunchaku/releases

2-2. Portable版 Python でインストール

ダウンロードした *.whl ファイルをComfyUI_windows_portable フォルダ直下にコピーします。

次にコマンドプロンプトを開き、以下を実行：

.\python_embeded\python.exe -m pip install XXX

XXX はダウンロードした whl ファイル名です。

例：

.\python_embeded\python.exe -m pip install nunchaku-1.1.0+cu121-cp310-win_amd64.whl

3. diffusers を 0.36.0 にアップデートする

Z-Image-Turbo では diffusers のバージョン互換性が重要です。Portable版 Python を使って、以下を実行します。

.\python_embeded\python.exe -m pip install --upgrade diffusers==0.36.0

他のバージョンが入っている場合、動かない・ノードが出ない原因になることがあります。

4. アンオフィシャル Z-Image-Turbo Loader をインストール

現時点では 公式 Nunchaku ComfyUI Plugin が Z-Image-Turbo に未対応のため、以下のアンオフィシャル実装を使用します。

4-1. custom_nodes に移動

cd ComfyUI_windows_portable\ComfyUI\custom_nodes

4-2. git clone

git clone https://github.com/ussoewwin/ComfyUI-nunchaku-unofficial-z-image-turbo-loader

※ 将来的に公式プラグインが対応すれば、この手順は不要になる可能性があります（2025/12/27 時点では未対応）

5. ComfyUI を起動してワークフローを組む

ここまで完了したら ComfyUI を起動します。

ワークフローの考え方

基本構成は Nunchaku-Qwen-Image のワークフローをベースにして：

DiT Loader ノード
- Nunchaku-Qwen-Image DiT Loader
- ↓
- Nunchaku-ussoewwin Z-Image-Turbo DiT Loader に置き換え

選択するもの

モデル：Z-Image-Turbo 用 DiT
CLIP：対応するもの
VAE：モデルに合ったもの

これで Z-Image-Turbo が動作します。

参考までにワークフローは記事に添付しています。

（過去のワークフローの使いまわしなので、あまり優れたものではありませんが…）

まとめ

本記事は ComfyUI Windows Portable版専用
Nunchaku v1.1.0 + diffusers 0.36.0 がポイント
Z-Image-Turbo は アンオフィシャル Loader が必須（現時点）
公式対応が来るまではこの構成が安定

同じところで詰まっている人の助けになれば幸いです。