ComfyUI-Nunchaku QwenImage＆ZImageTurboLoraStack

<table align="center"> <tr> <td align="center" bgcolor="#3478ca" width="88" height="36"><font color="#ffffff"><b>EN</b></font></td> <td align="center" bgcolor="#e5e7eb" width="88" height="36"><a href="zhmd/README.md"><font color="#4b5563"><b>中文</b></font></a></td> </tr> </table>

A ComfyUI custom node for loading and applying LoRA (Low-Rank Adaptation) to Nunchaku Qwen Image and Z-ImageTurbo models. 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.4 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

<img src="images/single_loader.png" alt="NunchakuQwenImageLoraLoader: Single LoRA loader" width="400">

• NunchakuQwenImageLoraStack: Multi LoRA stacker with dynamic UI (Legacy)

<img src="images/legacy_stack.png" alt="NunchakuQwenImageLoraStack: Multi LoRA stacker with dynamic UI (Legacy)" width="400">

• 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.

<img src="images/qiv1_stack.png" alt="NunchakuQwenImageLoraStackV1: Multi LoRA stacker with rgthree-style UI" width="400">

• 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.

<img src="images/qiv2_stack.png" alt="NunchakuQwenImageLoraStackV2: Multi LoRA stacker with dynamic UI - ComfyUI Nodes 2.0 (Beta) compatible" width="400">

• 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.

<img src="images/qiv3_stack.png" alt="NunchakuQwenImageLoraStackV3: Multi LoRA stacker with dynamic UI - ComfyUI Nodes 2.0 (Beta) compatible" width="400">

• 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.

<img src="images/zitlorav1.png" alt="NunchakuZImageTurboLoraStackV1: Z-Image-Turbo LoRA stacker with rgthree-style UI" width="400">

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

<img src="images/zitv4_stack.png" alt="NunchakuZImageTurboLoraStackV4: Z-Image-Turbo LoRA stacker with dynamic UI - Standard ComfyUI LoRA loader format (CLIP input/output) - ComfyUI Nodes 2.0 compatible" width="400">

• NunchakuQI&ZITDiffsynthControlnet: DiffSynth ControlNet support node for Nunchaku Qwen Image & Z-ImageTurbo

• Krea2ControlNetLoraLoader: Krea2 depth controlnet-lora loader

<img src="images/krea2_controlnet_lora.png" alt="Krea2ControlNetLoraLoader Usage" width="420">

Basic Usage

For Nunchaku Qwen Image models:

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

For Nunchaku Z-Image-Turbo models:

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

Diffsynth ControlNet Usage

1. Load your diffsynth ControlNet model patch using Model Patch Loader from ComfyUI-NunchakuFluxLoraStacker
2. The Model Patch Loader (ModelPatchLoaderCustom) supports CPU offload, allowing you to load ControlNet patches to CPU memory to save VRAM
3. Connect the MODEL_PATCH output to the model_patch input of NunchakuQI&ZITDiffsynthControlnet node
4. Connect your Nunchaku Qwen Image model, VAE, and control image
5. Set the ControlNet strength and connect to your workflow
6. Krea2 depth support and usage: add Krea2ControlNetLoraLoader, select your Krea2 depth controlnet-lora file (for example: krea2-depth-control-lora.safetensors), then connect its MODEL_PATCH output to NunchakuQI&ZITDiffsynthControlnet model_patch

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

Troubleshooting

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

Problem: The nunchaku package is not installed.

Solution:

1. Install ComfyUI-nunchaku plugin from the o