Nunchaku Qwen-Image DiT Loader

Qwen-Image is a 20B model. That's the problem this node exists to solve. The full BF16 stack is a monster that most people can't fit, so the usual answer is GGUF or fp8 to shrink it - and Nunchaku is a third, more aggressive route: 4-bit SVDQuant weights that run through a custom inference engine instead of just being cast down. NunchakuQwenImageDiTLoader is the loader that pulls one of those pre-quantized Qwen-Image files into ComfyUI and hands you a MODEL to sample from.

The reason people bother: speed and VRAM, both. Nunchaku's own release notes say Qwen-Image's transformer can be squeezed to roughly 3 GiB of VRAM with async offloading and "no performance loss," and that is the pitch in a sentence. It's why the corpus lit up - over a thousand threads mention Nunchaku, hundreds in 2026 alone. If you've been priced out of the 20B family, this is the door in.

How it works

SVDQuant is what makes 4-bit not look like garbage. Naive 4-bit quantization dies on outliers - a few huge weight values wreck the whole tensor when you crush the range. SVDQuant migrates those outliers into a small low-rank branch computed in higher precision, lets the bulk of the model live in 4-bit, and Nunchaku's engine fuses the two so the low-rank part doesn't become its own speed tax. Net result is a 4-bit model whose output stays close to the 16-bit original, running on a purpose-built kernel rather than dequantizing on the fly the way GGUF does.

The catch - and it's the big one - is that this only works on models Nunchaku has already quantized. You feed it their Qwen-Image build from the nunchaku-ai HuggingFace repo, not a random safetensors and not a GGUF. The model_name dropdown lists whatever nunchaku Qwen files you've dropped in your models folder.

The inputs and outputs that matter

• model_name - the pre-quantized Qwen-Image file. If the dropdown is empty, you haven't downloaded one yet (see below).
• cpu_offload (auto / enable / disable, default auto) - leave it on auto and it decides based on your VRAM. Force enable on a tight card to push blocks to system RAM.
• num_blocks_on_gpu (1–60, default 1) - how many transformer blocks stay resident on the GPU when offloading. Higher is faster but eats VRAM; nudge it up if you have headroom.
• use_pin_memory (default disable) - can speed up the CPU↔GPU shuffle at the cost of pinned host RAM. Optional tuning, safe to ignore at first.

Output is a single MODEL, which wires straight into your KSampler like any other. Pair it with a Nunchaku text encoder loader and a normal VAE and you have a full Qwen-Image graph.

How to install it

Two parts, and missing the second is the classic mistake. First the node pack: in ComfyUI Manager search "ComfyUI-nunchaku" and install, or

cd ComfyUI/custom_nodes
git clone https://github.com/mit-han-lab/ComfyUI-nunchaku

then restart. Second - and this is the part people forget - Nunchaku needs its backend wheel, the actual inference engine, matched to your PyTorch/Python/CUDA. The pack ships a NunchakuWheelInstaller node for exactly this; run it once. Then grab a quantized Qwen-Image model from the nunchaku-ai HuggingFace org: INT4 builds for RTX 20/30/40-series, NVFP4 builds for Blackwell 50-series. Wrong precision for your card and it won't load.

Common issues & troubleshooting

Dropdown is empty / node loads nothing. You installed the plugin but not a model. Nunchaku will not accept a plain Qwen safetensors - you need their quantized file in models/diffusion_models.

Import errors or the node never appears. That's the wheel, not the node. Install the matching backend with NunchakuWheelInstaller and restart. A wheel built for a different Torch version silently fails to load.

Wrong file for your GPU. INT4 vs NVFP4 is a hard split, not a preference. A 4090 wants INT4; a 5090 wants NVFP4. Downloading the wrong one is the most common "why won't it run" on newer cards.

Still tight on VRAM. Keep cpu_offload on auto, and if you're offloading, don't crank num_blocks_on_gpu - that's the setting that quietly refills your VRAM.