ComfyUI-Nunchaku QwenImage＆ZImageTurboLoraStack

August 13, 2026 · View on GitHub

A ComfyUI custom node for loading and applying LoRA (Low-Rank Adaptation) to Nunchaku Qwen Image and Z-ImageTurbo models, plus a Krea2 depth/openpose ControlNet LoRA loader. ComfyUI Nodes 2.0 compatible. Requires Nunchaku 1.2.0+ and ComfyUI-Nunchaku 1.2.0+ for v4 functionality.

⚠️ DEVELOPMENT STATUS

Currently under development and testing. Debug logs are being output extensively. This does not affect functionality.

Latest release: v2.5.6 Release Notes

Source

This LoRA loader was extracted and modified from GavChap's fork:

Original Fork: GavChap/ComfyUI-nunchaku (qwen-lora-suport-standalone branch)
Extraction: LoRA functionality was extracted from the full fork to create an independent custom node
Integration: Modified to work with the official ComfyUI-nunchaku plugin

🎉 MAJOR UPDATE: v2.2.0 - Nunchaku Z Image Turbo LoRA Support Added!

For detailed technical explanation, see v2.2.0 Release Notes

🎉 MAJOR UPDATE: v1.60 - Simplified Installation (No Integration Required!)

For installation instructions, features, and requirements, see Installation Guide.

Upgrade Guide for v1.57 and Earlier Users

If you have v1.57 or earlier installed with integration code in ComfyUI-nunchaku's __init__.py, see UPGRADE_GUIDE_V1.57.md for detailed upgrade instructions.

Usage

Debug logs (optional)

By default, detailed debug logs are muted. If you want detailed debug output (Key Diffusion / key mapping inspection, [APPLY], [AWQ_MOD], etc.), set the environment variable nunchaku_log=1 before starting ComfyUI.

Available Nodes

NunchakuQwenImageLoraLoader: Single LoRA loader

NunchakuQwenImageLoraStack: Multi LoRA stacker with dynamic UI (Legacy)

NunchakuQwenImageLoraStack: Multi LoRA stacker with dynamic UI (Legacy)

NunchakuQwenImageLoraStackV1: Multi LoRA stacker with rgthree-style UI
- Clean, minimalist design inspired by Power Lora Loader (rgthree-comfy). Toggle, LoRA name, and strength per row.
- ⚠️ Note: Does not work properly with ComfyUI Nodes 2.0. Use the standard (LiteGraph) canvas.
- ⚠️ When using with ComfyUI Nodes 2.0, pressing F5 to refresh will reflect changes.

NunchakuQwenImageLoraStackV1: Multi LoRA stacker with rgthree-style UI

NunchakuQwenImageLoraStackV2: Multi LoRA stacker with dynamic UI - ComfyUI Nodes 2.0 (Beta) compatible
- AWQ Modulation Layer Support: Includes experimental support for applying LoRA to AWQ quantized modulation layers (img_mod.1 / txt_mod.1) via the "Apply AWQ Mod" toggle. This feature uses Runtime Monkey Patch with Manual Planar Injection to fix noise issues. ⚠️ Warning: This is an experimental feature currently implemented only in V2 nodes. If no issues are found, this feature will be applied to V1 and V3 nodes as well.

NunchakuQwenImageLoraStackV2: Multi LoRA stacker with dynamic UI - ComfyUI Nodes 2.0 (Beta) compatible

NunchakuQwenImageLoraStackV3: Multi LoRA stacker with dynamic UI - ComfyUI Nodes 2.0 (Beta) compatible
- AWQ Modulation Layer Support: AWQ quantized modulation layers (img_mod.1 / txt_mod.1) LoRA application is always enabled (no switch needed). This feature uses Runtime Monkey Patch with Manual Planar Injection to fix noise issues. ✅ V3 nodes always apply AWQ modulation layer LoRA by default.

NunchakuQwenImageLoraStackV3: Multi LoRA stacker with dynamic UI - ComfyUI Nodes 2.0 (Beta) compatible

NunchakuZImageTurboLoraStackV1: Z-Image-Turbo LoRA stacker with rgthree-style UI
- Clean, minimalist design inspired by Power Lora Loader (rgthree-comfy). Toggle, LoRA name, and strength per row. For official Nunchaku Z-Image loader only. Uses compose_loras_v2.
- ⚠️ Note: Does not work properly with ComfyUI Nodes 2.0. Use the standard (LiteGraph) canvas.
- ⚠️ When using with ComfyUI Nodes 2.0, pressing F5 to refresh will reflect changes.

NunchakuZImageTurboLoraStackV1: Z-Image-Turbo LoRA stacker with rgthree-style UI

NunchakuZImageTurboLoraStackV4: Z-Image-Turbo LoRA stacker with dynamic UI - Standard ComfyUI LoRA loader format (CLIP input/output) - ComfyUI Nodes 2.0 compatible

NunchakuZImageTurboLoraStackV4: Z-Image-Turbo LoRA stacker with dynamic UI - Standard ComfyUI LoRA loader format (CLIP input/output) - ComfyUI Nodes 2.0 compatible

NunchakuQI&ZITDiffsynthControlnet: DiffSynth ControlNet support node for Nunchaku Qwen Image, Z-ImageTurbo & Krea2 (depth / openpose)
Krea2ControlNetLoraLoader: Krea2 controlnet-lora loader (depth & openpose)
- Auto-detects the Krea2 control sub-type from the LoRA file: depth (first.weight expansion route) or openpose (pure block LoRA + native reference-latent route). Routing is strictly exclusive.

Basic Usage

For Nunchaku Qwen Image models:

Load your Nunchaku Qwen Image model using Nunchaku Qwen Image DiT Loader
Add either NunchakuQwenImageLoraLoader or NunchakuQwenImageLoraStack node
Select your LoRA file and set the strength
Connect to your workflow

For Nunchaku Z-Image-Turbo models:

Load your Nunchaku Z-Image-Turbo model using Nunchaku Z-Image DiT Loader (official ComfyUI-Nunchaku)
Add Nunchaku Z-Image-Turbo LoRA Stack V4 node
Connect CLIP input (required in v4)
Select your LoRA file and set the strength
Connect to your workflow

Diffsynth ControlNet Usage

Load your diffsynth ControlNet model patch using Model Patch Loader from ComfyUI-NunchakuFluxLoraStacker
The Model Patch Loader (ModelPatchLoaderCustom) supports CPU offload, allowing you to load ControlNet patches to CPU memory to save VRAM
Connect the MODEL_PATCH output to the model_patch input of NunchakuQI&ZITDiffsynthControlnet node
Connect your Nunchaku Qwen Image model, VAE, and control image
Set the ControlNet strength and connect to your workflow
Krea2 control support (depth & openpose): add Krea2ControlNetLoraLoader, select your Krea2 controlnet-lora file, then connect its MODEL_PATCH output to the model_patch input of NunchakuQI&ZITDiffsynthControlnet. The node auto-detects the Krea2 sub-type:
- Depth (e.g. krea2-depth-control-lora.safetensors): expanded first-projection route with control-latent injection. This is the original Krea2 depth behavior, unchanged.
- OpenPose (e.g. krea2_turbo_openpose_controlnet.safetensors): pure block-LoRA route on diffusion_model.blocks + diffusion_model.txtfusion (layerwise/refiner), with the pose image injected as a native Krea2 reference latent (index_timestep_zero). Keep use_kv_cache enabled (default) - this matches the ai-toolkit kv_cache training convention the openpose control LoRA was trained with.

Krea2 Control (Depth & OpenPose)

NunchakuQI&ZITDiffsynthControlnet auto-detects the Krea2 control sub-type from the loaded LoRA file and applies a dedicated, self-contained route - no external nodes required.

Krea2 Depth Control

Load the depth control LoRA with Krea2ControlNetLoraLoader (e.g. krea2-depth-control-lora.safetensors)
Connect its MODEL_PATCH to NunchakuQI&ZITDiffsynthControlnet's model_patch
Connect your Krea2 model, VAE and the depth image; set strength

How it works:

The depth LoRA provides an expanded first projection (2x input channels). It is injected through a runtime _Krea2FirstProjection shim scaled by strength
Block LoRA patches (rank 64) are applied to the DiT blocks
The depth image is VAE-encoded and fed into the expanded first projection so depth conditions the generation from the very first layer

Krea2 OpenPose Control

The krea2_turbo_openpose_controlnet.safetensors control LoRA is applied through a dedicated, self-contained route in NunchakuQI&ZITDiffsynthControlnet:

Load the openpose control LoRA with Krea2ControlNetLoraLoader
Connect its MODEL_PATCH to NunchakuQI&ZITDiffsynthControlnet's model_patch
Connect your Krea2 model, VAE and the pose image; set strength
Keep use_kv_cache = True (default) for the isolated reference K/V mode

How it works:

256 block LoRA patches (rank 32) applied to all 28 DiT blocks plus the txtfusion layerwise/refiner blocks
The pose image is VAE-encoded and injected as a native Krea2 reference latent (index_timestep_zero), the conditioning pathway this control LoRA was trained against
use_kv_cache runs one t=0 reference pass that precomputes every block's K/V and injects them as extra attention keys each step (no per-step ref tokens in the sequence)

Exclusivity: the Krea2 route is sub-classified strictly (depth vs openpose) and the whole Krea2 branch is fully isolated from the Qwen Image / Z-Image / Nunchaku routes - existing workflows using those routes are unaffected.

Reference: ostris' comfyui-krea2-ostris-edit TextEncode node and pysssss' krea2_controlnet_pose.json workflow were used as reference; this repository implements the same pose-control effect standalone.

Features

Easy Installation: Simple git clone installation
Independent Operation: No integration code required (v1.60+)
Automatic Node Discovery: ComfyUI automatically loads the custom node
Error Handling: Comprehensive error checking and user feedback
Issue #1 Fixed: Resolved ComfyUI\custom_nodes not found error with improved path detection (thanks to @mcv1234's solution)
Issue #2 Fixed: Fixed UTF-8 encoding error causing SyntaxError: (unicode error) by using dedicated Python script for proper UTF-8 encoding (thanks to @AHEKOT's bug report)
Issue #3 Fixed (v1.4.0): Resolved Node break cached progress error by implementing proper IS_CHANGED method with hash-based change detection (thanks to @AHEKOT's bug report)
Issue #10 Fixed: Added portable ComfyUI support with embedded Python detection (Issue #10) - Special Thanks: This crucial feature was suggested by @vvhitevvizard, who identified the need for embedded Python support in portable ComfyUI installations. Without this suggestion, portable ComfyUI users would not have been able to use this LoRA loader.
PR #48 Merged (v2.3.8): Improved PEFT format LoRA detection and added safety skip logs (PR #48) - Special Thanks: We are deeply grateful to @avan06 for identifying and fixing a critical mapping defect that caused PEFT format LoRAs to be incorrectly skipped. This fix significantly improves LoRA format compatibility and ensures proper detection of LoRA files created with Hugging Face PEFT library.
PR #49 Merged (v2.4.0): Added Nunchaku Qwen Image LoRA Stack V1 with rgthree-style UI (PR #49) - Special Thanks: We are deeply grateful to @avan06 for proposing the clean, minimalist interface inspired by Power Lora Loader (rgthree-comfy). This contribution brings an elegant LoRA row layout with toggle, LoRA name, and strength control. We had long felt the need for such a UI but were unable to implement it with our technical skills; this PR fulfilled that need.

Requirements

ComfyUI
ComfyUI-nunchaku plugin (official version, no modification required)
PyTorch
Python 3.11+

Compatibility

This node is designed to work with:

ComfyUI-nunchaku plugin (official version)
Nunchaku Qwen Image models
Standard ComfyUI workflows

AMD / ROCm Compatibility

nunchaku requires NVIDIA CUDA and is not available on AMD/ROCm systems. On AMD/ROCm (or any machine where the nunchaku package cannot be imported), this custom node automatically detects the missing dependency and adapts:

Disabled: All nunchaku-dependent nodes are not registered and will not appear in the node list:
- NunchakuQwenImageLoraLoader / NunchakuQwenImageLoraStack
- NunchakuQwenImageLoraStackV1 / V2 / V3
- NunchakuZImageTurboLoraStackV1 / V4
Still available: The nunchaku-independent Krea2 ControlNet nodes remain fully functional:
- Krea2ControlNetLoraLoader — loads a Krea2 ControlNet LoRA into a MODEL_PATCH
- NunchakuQwenImageDiffsynthControlnet — applies the control (the Krea2 route of this node does not require nunchaku; the Z-Image / Nunchaku-QwenImage routes are only reachable when nunchaku is installed)

At startup, a [ROCm/AMD] nunchaku is not available... warning is logged when the dependency is missing. If a legacy workflow still references a disabled node, you get a clear RuntimeError ("nunchaku is required...") instead of an obscure import failure.

Troubleshooting

Error: "ModuleNotFoundError: No module named 'nunchaku'"

Problem: The nunchaku package is not installed.

Solution:

Install ComfyUI-nunchaku plugin from the official repository
Follow the nunchaku installation instructions to install the nunchaku wheel
Restart ComfyUI

Issue #25: ComfyUI 0.4.0+ Model Management Errors

Status: ⚠️ Environment Dependent - May require ComfyUI core fixes

For detailed information, see COMFYUI_0.4.0_MODEL_MANAGEMENT_ERRORS.md.

Related Issues:
- Issue #25 - AttributeError: 'NunchakuModelPatcher' object has no attribute 'pinned' and deepcopy errors with model_config
- Issue #33 - AttributeError: 'NoneType' object has no attribute 'to' in to_safely method (Fixed in v2.1.0)
- ComfyUI Issue #6590 - 'NoneType' object has no attribute 'shape'
- ComfyUI Issue #6600 - 'NoneType' object is not callable (Loader-related)
- ComfyUI Issue #6532 - Crash after referencing models after model unload

Error: "No module named 'diffusers.models.transformers.transformer_z_image'"

Problem: This error occurs when using Qwen-Edit models or Z-Image-Turbo models with an outdated diffusers library version.

Error Message: ModuleNotFoundError: No module named 'diffusers.models.transformers.transformer_z_image'

Root Cause: The most likely cause is that the diffusers library version is too old and does not include the transformer_z_image module, which is required for Z-Image-Turbo model support. When ComfyUI-nunchaku's model loader tries to load Z-Image-Turbo models (or Qwen-Edit models that may be detected as Z-Image format), it attempts to import this module, but it doesn't exist in older diffusers versions. This module was added in a later version of diffusers to support Z-Image-Turbo models.

Solution: Update the diffusers library to the latest version:

If using a virtual environment (venv):

pip install --upgrade diffusers

If using ComfyUI's embedded Python:

ComfyUI\python_embeded\python.exe -m pip install --upgrade diffusers

How to Verify: After updating, restart ComfyUI and try loading your model again. The error should be resolved.

Related Issues: Issue #38, Issue #40

Known Limitations

LoKR (Lycoris) LoRA Support

Status: ❌ Not Supported
Issue: LoRAs in LoKR format (created by Lycoris) are not supported.
- Important Note: This limitation applies specifically to Nunchaku quantization models. LoKR format LoRAs may work with standard (non-quantized) Qwen Image models, but this node is designed for Nunchaku models only.
- ⚠️ Development History: We have spent considerable time analyzing the internal structure of LoKR format and performing extensive mapping tests. Despite these efforts, we have not been able to find a successful way to apply LoKR weights to Nunchaku quantization models. The experimental conversion code has been tested but ultimately disabled due to incompatibility issues.
- LoKR weights are automatically skipped when detected (experimental conversion code is disabled).
- Converting to Standard LoRA using SVD approximation (via external tools or scripts) has also been tested and found to result in noise/artifacts when applied to Nunchaku quantization models.
Conclusion: At this time, we have not found a way to successfully apply LoKR weights to Nunchaku models. Please use Standard LoRA formats.
Supported Formats:
- ✅ Standard LoRA (Rank-Decomposed):
  - Supported weight keys:
    - lora_up.weight / lora_down.weight
    - lora.up.weight / lora.down.weight
    - lora_A.weight / lora_B.weight
    - lora.A.weight / lora.B.weight
  - These are the standard formats produced by Kohya-ss, Diffusers, and most training scripts.
- ✅ PEFT Format LoRA (v2.3.8+):
  - Supported weight keys (examples):
    - lora_A.default.weight / lora_B.default.weight
    - lora.up.default.weight / lora.down.default.weight
  - Additional tags between lora_A/lora_B and .weight are supported (e.g. .default).
  - These formats are produced by the Hugging Face PEFT library. Support was added in v2.3.8 (PR #48).
- ❌ LoKR (Lycoris): Not supported (Keys like lokr_w1, lokr_w2)
- ❌ LoHa: Not supported (Keys like hada_w1, hada_w2)
- ❌ IA3: Not supported
Related Issues:
- Issue #29 - LyCORIS / LoKr Qwen Image LoRA not recognized by ComfyUI
- Issue #44 - [MISS] Module found but unsupported/missing proj_down/proj_up (performance slowdown issue fixed in v2.2.8)

context_refiner and noise_refiner Layer Support

Status: ❌ Not Currently Supported
Issue: LoRA keys for context_refiner and noise_refiner layers are not currently supported. These are specialized layers used in Z-Image-Turbo models for refiner functionality.
Details:
- ⚠️ Testing Limitation: We have not tested LoRAs that contain context_refiner and noise_refiner layers with actual models. The reason we cannot test them is that we do not know which LoRAs are in this format. If we can identify specific LoRAs that contain these layers, we can proceed with testing.
- Without testing, we cannot determine if correct key mappings are possible for these layers. The current key mapping system does not include mappings for these layers, and they will not work at this time.
Conclusion: Support for context_refiner and noise_refiner layers is not implemented because we have not been able to test LoRAs containing these layers. Even if we test them, it is unknown whether correct key mappings can be determined. Please use LoRAs that target the standard transformer layers only.
Related Issues:
- #41 - 无法加载context_refiner和noise_refiner层的参数

RES4LYF Sampler Compatibility Issue

Status: ✅ Fixed in ComfyUI-nunchaku v1.0.2
Issue: Device mismatch errors occurred when using RES4LYF sampler with LoRA (Issue #7, Issue #8)
Fix: The issue was fixed in ComfyUI-nunchaku v1.0.2 by @devgdovg in PR #600. This fix was implemented in ComfyUI-nunchaku's codebase, not in this LoRA loader.
Requirement: Update to ComfyUI-nunchaku v1.0.2 or later to use RES4LYF sampler with LoRA
Related Issues:
- Issue #7 - RES4LYF sampler device mismatch error
- Issue #8 - RES4LYF sampler compatibility issue