Z-Image GGUF Standalone Loader

The name is honest: this is a standalone GGUF reader, and it exists because Z-Image on a low-VRAM card is a GGUF story. Alibaba's 6B model is famously small, but "small" gets you quantized to something you can actually run on 4-8GB. This node loads the quantized transformer and the quantized Qwen3-4B text encoder as raw state dicts - not a ready-to-sample model, but the raw material every other "raw" node in the Zlycoris pack works on.

What it actually loads

The two dropdowns read from the same folders City96's ComfyUI-GGUF pack uses, so if you've ever run GGUF Flux or Z-Image, your files are already in the right place:

• transformer_name → ComfyUI/models/unet_gguf/
• text_encoder_name → ComfyUI/models/clip_gguf/

There's a type dropdown with seven architectures: stable_diffusion, stable_diffusion_xl, sd3, flux, qwen_image, gemma, hunyuan_di_t. For Z-Image you want qwen_image for the transformer. That's not just bookkeeping - it decides whether the node runs its padding fix.

Why the padding fix matters

GGUF quantizers pad tensors to block-aligned sizes, which shows up as fake dimensions. The node scans for the two it knows about - 2720 → 2560 (Qwen/LLM hidden size) and 4352 → 4096 (Gemma) - and trims them back. Pick the wrong type and those pads stay, the tensor shapes won't match what the injector expects, and you get the classic "size mismatch" wall of errors right at the merge step. This is the single most common thing that bites people.

Where the output goes

RAW_MODEL and RAW_CLIP are Zlycoris's internal wrapper type - a state dict plus the file path, not a ComfyUI MODEL/CLIP. You've got three sane destinations:

1. Run it: feed both into ZImageGGUFInjector, which rebuilds them into a real MODEL/CLIP using GGML custom ops. This is your low-VRAM generation path.
2. Merge it: pipe into ZImageRawModelMerge / ZImageRawClipMerge to blend quantized checkpoints on the raw level.
3. Export it: dequantized state in hand, save via the pack's save nodes.

Note the dequantization happens at load - the node hands back floating-point tensors, so a Q4 file takes a while to unfurl. The code even warns that some low quant types fall back to a numpy dequant path that is "incredibly slow." If it feels stuck on load, that's usually it, not a crash.

Install

ComfyUI Manager (search ComfyUI-Zlycoris) or:

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

Restart ComfyUI. This pack pulls a genuinely heavy dependency list - gguf, transformers, diffusers, optimum, lycoris, sentencepiece among others - so the first install takes a while and a missing gguf module will break this node specifically.

Gotchas worth knowing

• The GGUF machinery here is vendored from City96's ComfyUI-GGUF (the file headers say so). It's a raw-loading path on top of that, so don't double-install thinking they conflict - they use the same model folders but different loaders.
• If the type enum doesn't list your model family, pick the closest and expect to verify shapes by hand. The padding fix only knows Qwen and Gemma sizes.
• Low-quant GGUF (Q3/Q2) plus the numpy dequant fallback is the slowest possible load. If your card can breathe, Q8 is basically fp16 quality at half the size - the padding fix doesn't care which tier you feed it.