Z-Image GGUF Injector

The GGUF half of Zlycoris is a two-node story: ZImageGGUFStandaloneLoader reads quantized files into raw state dicts, and ZImageGGUFInjector turns those raw dicts into a sampleable MODEL and CLIP - with the GGML operations and model patcher that quantized weights actually need. If the standalone loader is the reader, this is the builder. They're sold as a pair: you can't sample off the loader alone, and you shouldn't feed non-GGUF raw data into this injector.

How it works

For the model, the node calls ComfyUI's load_diffusion_model_state_dict with custom_operations set to the pack's GGML ops - the custom linear layers that know how to run quantized tensors - then wraps the result in a GGUFModelPatcher clone. For the CLIP, it calls load_text_encoder_state_dicts with the GGML ops plus the text-encoder offload device, again wrapped in the GGUF patcher. That patcher is the piece that keeps the quantized tensors dequantizing on the fly during sampling instead of exploding into full-precision memory.

The one input that isn't just raw data is clip_type, a dropdown with the same seven architectures as the loader (stable_diffusion, stable_diffusion_xl, sd3, flux, qwen_image, gemma, hunyuan_di_t). It selects the CLIPType used to build the text encoder. For Z-Image that's qwen_image.

The workflow

Loader → Injector → sampler, with nothing in between:

ZImageGGUFStandaloneLoader (RAW_MODEL, RAW_CLIP) → ZImageGGUFInjector (MODEL, CLIP) → KSampler.

That's the low-VRAM Z-Image path: a quantized checkpoint in unet_gguf/, a quantized Qwen encoder in clip_gguf/, and both fit in a fraction of the VRAM a full-precision model would demand. The community runs Z-Image on as little as 4GB with GGUF, and this pair is how the Zlycoris pack does it.

Install

ComfyUI Manager (search ComfyUI-Zlycoris) or:

cd ComfyUI/custom_nodes
git clone https://github.com/TripleHeadedMonkey/ComfyUI-Zlycoris.git

Restart ComfyUI. The gguf package is a hard dependency of this node - if import fails at load time, that's the first thing to check.

Where people get burned

• Wrong clip_type = wrong text encoder construction. Pick stable_diffusion for a Qwen encoder and the CLIP may build with the wrong assumptions. Match the type to what you actually loaded in the standalone loader - if the loader applied its padding fix for qwen_image, the injector should see qwen_image too.
• GGUF injector is only for GGUF raw data. It's tempting to use it as a generic "raw → model" node, but it force-applies GGML ops. Feed it a full-precision raw dict and you're running float weights through quantized linear ops - slower, and wrong. Use ZImageComfyInjector for non-quantized raw.
• The GGUF patcher keeps quantization on the CLIP too. That's usually great for VRAM, but if you see text-encoder quality issues at very low quant levels (Q3/Q2 Qwen), that's the encoder, not the injector - the GGUF quality ladder (Q8 ≈ fp16, Q4_K_M acceptable, Q3/Q2 degraded) applies per-component.
• Injection is real model construction. First inject after loading costs the same time/VRAM as a normal model load; don't rebuild the model in a loop.