ussoewwin/ComfyUI-QwenImageLoraLoader

What it is

ComfyUI‑QwenImageLoraLoader is a custom node package for ComfyUI – a visual, node‑based interface for building Stable Diffusion‑style image generation pipelines. The nodes in this repository let you load and apply LoRA (Low‑Rank Adaptation) weights to the Qwen‑Image and Z‑Image‑Turbo models that are provided by the Nunchaku plugin. In addition, the package includes loaders for Krea2 depth/open‑pose ControlNet LoRAs and a DiffSynth‑style ControlNet node.

Why it matters

• LoRA support – LoRA files are tiny, fine‑tuned weight deltas that let you adapt a large diffusion model (e.g., Qwen‑Image) to a new style or subject without retraining the whole model. This package makes adding those LoRAs as simple as dropping a file into a node and setting a strength slider.
• Multi‑LoRA stacking – The “Stack” nodes let you combine several LoRAs in one workflow, each with its own enable toggle and strength, mirroring the popular rgthree Power LoRA Loader UI.
• AWQ quantisation handling – Experimental support for applying LoRA to AWQ‑quantised modulation layers (img_mod.1 / txt_mod.1) is built in, which is useful for low‑VRAM setups.
• ControlNet integration – Dedicated nodes load Krea2 depth/open‑pose ControlNet LoRAs and a DiffSynth ControlNet route, expanding the range of conditioning options.
• Compatibility – Works with the official ComfyUI‑nunchaku plugin (v1.2.0+), supports the newer ComfyUI Nodes 2.0 UI (beta), and gracefully disables itself on AMD/ROCm systems where the nunchaku package is unavailable.

Core features

Feature	Description
Single LoRA loader	NunchakuQwenImageLoraLoader – load one LoRA and set its strength.
Stack V1	rgthree‑style UI, works on the classic LiteGraph canvas (not Nodes 2.0).
Stack V2	Dynamic UI, beta support for Nodes 2.0, includes a toggle for applying LoRA to AWQ modulation layers.
Stack V3	Same as V2 but the AWQ modulation‑layer LoRA is always applied.
Z‑Image Turbo Stack V1 / V4	LoRA stacking for the Z‑Image‑Turbo model family; V4 uses the standard CLIP‑in/‑out LoRA format and is Nodes 2.0‑compatible.
DiffSynth ControlNet & Krea2	NunchakuQwenImageDiffsynthControlnet loads DiffSynth‑style ControlNet patches; Krea2ControlNetLoraLoader auto‑detects depth vs. open‑pose LoRAs and routes them appropriately.
Debug logging	Optional verbose logs via nunchaku_log=1.
Installation	Simple git clone into ComfyUI’s custom_nodes folder; no extra integration code required from v1.60 onward.
Error handling	Detects missing nunchaku dependency, provides clear runtime errors, and includes fixes for common UTF‑8, path‑detection, and model‑management issues.

Who should use it

• Artists & hobbyists building ComfyUI workflows with Qwen‑Image or Z‑Image‑Turbo models who want to experiment with LoRA‑based style or subject adaptation.
• Researchers exploring low‑VRAM quantised models (AWQ) and need a way to apply LoRA on top of them.
• Developers extending ComfyUI with custom ControlNet conditioning (depth, pose) who need a ready‑made loader that auto‑detects the LoRA type.

Getting started (quick steps)

1. Install prerequisites – ComfyUI, the official ComfyUI‑nunchaku plugin (≥ 1.2.0), PyTorch, Python 3.12+.
2. Add the node package:

   cd path/to/ComfyUI/custom_nodes
   git clone https://github.com/ussoewwin/ComfyUI-QwenImageLoraLoader.git
   

3. Restart ComfyUI – the new nodes appear in the node palette.
4. Load a model – use the existing Nunchaku Qwen Image DiT Loader or Nunchaku Z‑Image DiT Loader node.
5. Add a LoRA loader – drop a NunchakuQwenImageLoraStackV2 (or any stack version) into the workflow, point it at a .safetensors LoRA file, set the strength, and connect its output to the model input.
6. (Optional) Add ControlNet – load a Krea2 depth/open‑pose LoRA with Krea2ControlNetLoraLoader and connect it to the DiffSynth ControlNet node.
7. Run – generate images with the combined model + LoRA + ControlNet conditioning.

Limitations & open issues

• Nodes 2.0 compatibility – V1 stack nodes do not work with the new UI; only V2/V3/V4 are beta‑compatible.
• ControlNet on Nunchaku‑quantised Qwen Image – The built‑in DiffSynth ControlNet cannot be used with the W4A4‑quantised Qwen Image model due to hidden‑state scaling mismatches (see the “Known Limitations” section).
• AMD/ROCm – The core Nunchaku‑dependent nodes are disabled when the nunchaku package cannot be imported; only the Krea2‑related nodes remain functional.
• Experimental AWQ support – Applying LoRA to AWQ modulation layers is still experimental and may change in future releases.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.