ZImage SDNQ Loader

This is the node the whole pack is built around. ZImageSDNQPipelineLoader loads Z-Image - Alibaba's 6B model that essentially ended Flux 2's launch party by running great on a 12GB card - along with its tokenizer, text encoder, VAE, and scheduler, and hands you a single pipeline object that every sampler in the pack consumes. The SDNQ part is the point: the default precision is an int8-quantized checkpoint, and you can drop to uint4 if your VRAM is genuinely small.

If you've come from standard ComfyUI, this replaces the whole CheckpointLoader → CLIPTextEncode → VAELoader dance. One node, one typed output, everything downstream just works. That's the trade the pack makes: it gives up the fine-grained native graph in exchange for a much simpler setup and quantized checkpoints the native loader didn't support at the time.

What the inputs mean

Most defaults are fine to leave alone. The ones that matter:

• model_source - a dropdown of diffusers model folders found under models/diffusers/ (it looks for folders containing model_index.json). Defaults to <manual>, meaning "let precision decide."
• precision - auto, full, q8, q4. This is where SDNQ lives. auto resolves to q8 on CUDA and MPS, full elsewhere. q8 is the SDNQ int8 checkpoint (Z-Image-Turbo-SDNQ-int8), q4 the SDNQ uint4 (Z-Image-Turbo-SDNQ-uint4-svd-r32), full the plain BF16 Tongyi-MAI/Z-Image-Turbo. Pick q4 when VRAM is tight, full when you have headroom and want the reference behavior.
• quantized_matmul - auto, enable, disable. Toggles SDNQ's quantized matrix multiply, the thing that makes the quantized weights actually fast. auto probes your GPU and decides. If you get a message about it being disabled for your platform, that's SDNQ declining rather than something you broke.
• local_files_only (default true) - the gotcha. With <manual> selected and nothing in model_source_custom, the node falls back to a Hugging Face model ID and tries to load it via diffusers. But local_files_only=true means don't download anything. So the out-of-box behavior is: works fine if you've dropped the model into models/diffusers/ yourself, and fails with a "model not found" if you expected it to fetch from HF. Flip it to false if you want auto-download.
• model_source_custom - the escape hatch. Drop a path or HF ID in here and it overrides the dropdown entirely. This is how you point at a model the scanner doesn't see.

The rest - device, dtype, trust_remote_code, low_cpu_mem_usage - are the diffusers plumbing, and auto values are sane on nearly every setup.

What comes out

A single pipeline output of the pack's custom ZIMAGE_PIPELINE type. It feeds ZImageSDNQSamplerT2I, ZImageSDNQSamplerI2I, and ZImageSDNQLoRAApply. The loaded model is cached per-session, so re-queuing with the same settings is instant; only a settings change forces a reload.

Install and the real dependency story

The pack is small and has no requirements.txt in-repo, which is the first thing to know about installing it. ComfyUI Manager (search "Z-Image SDNQ") or:

cd ComfyUI/custom_nodes
git clone https://github.com/GeneralShan/comfyui-zimage-sdnq

Then restart. It needs a recent ComfyUI - the node API it uses requires >= 0.17.0. The Python side needs diffusers and sdnq for any use (they're the "required" deps in the README), plus timm and opencv-python-headless if you touch the control nodes. If your first queue dies on ModuleNotFoundError: sdnq, that's the fix, and it's a genuine first-run wall for people who install the pack and assume Manager pulled everything in:

pip install sdnq diffusers timm opencv-python-headless

diffusers and sdnq are the ones that actually matter for this node. Model placement: diffusers folders under models/diffusers/, and remember the local_files_only note above when you're deciding whether the loader should download for you.

One honest caveat about the whole approach: SDNQ is a newer quantization story than GGUF, and the community's early take was that SDNQ models came wrapped in heavy diffusers plumbing that's awkward in ComfyUI. This pack is a deliberate attempt to make that wrapper tolerable - a one-node loader, cached sessions, live LoRA attach. It works, but it's an opinionated wrapper, not the native graph. If you hit weird reload behavior or OOMs that don't make sense, the session cache is the first suspect, and ZImageSDNQClearCaches is the cure.