Nunchaku FLUX DiT Loader

This is the node that started the whole Nunchaku wave. NunchakuFluxDiTLoader loads a 4-bit SVDQuant version of a FLUX.1 model and gives you a MODEL that samples noticeably faster than the fp8 or GGUF you were probably using. That's the entire reason it exists, and it's why the pack blew up.

Some context on why that matters. Flux is 12B parameters, and running it on a consumer card has meant picking a quantization: fp8 is the near-lossless default on 12–24GB cards, GGUF is the Q4–Q8 ladder for when fp8 won't fit. Both save memory. Neither makes Flux fast - GGUF actually pays a dequantization tax, and gets worse when you stack LoRAs. Nunchaku's 4-bit takes a different swing: it's not just smaller, it runs on a dedicated kernel, so you get the VRAM saving and a real speedup on the same card.

How it works

SVDQuant is the trick underneath. Straight 4-bit quantization falls apart on outlier weights; SVDQuant peels those outliers into a small high-precision low-rank branch and lets the rest of the model live in 4-bit, then Nunchaku's engine fuses the two so the low-rank part doesn't cost you speed. You get 4-bit memory footprint with output that stays close to fp16 - roughly a third of the VRAM and a solid multiple of the throughput.

Same hard rule as the rest of the pack: it only loads Nunchaku-quantized Flux files, from the nunchaku-ai HuggingFace org. A normal flux1-dev.safetensors or a city96 GGUF will not go in here. The model_path dropdown shows whatever nunchaku Flux builds you've downloaded.

The inputs and outputs that matter

Most of the required inputs are set-and-forget - attention is fixed at nunchaku-fp16, data_type at float16, device_id at 0 for a single-GPU box. The two you'll actually touch:

• model_path - the quantized Flux file. The whole point; if it's empty you haven't downloaded one.
• cache_threshold (0–1, default 0) - this is First-Block Cache. Set it to 0 and caching is off (full quality every step). Bump it to ~0.1–0.15 and Nunchaku reuses work across steps for extra speed, at a small quality cost. It's the free-ish speed knob; leave it at 0 until you want more pace.
• cpu_offload (auto/enable/disable, default auto) - leave on auto; force enable on a low-VRAM card.
• i2f_mode (optional, enabled/always) - an int-to-float compatibility mode that matters mostly for older (20-series) GPUs. Default is fine unless you're on Turing.

Output is a MODEL - straight into your sampler.

How to install it

Two moving parts, and the second is where people trip. Node pack first: ComfyUI Manager → search "ComfyUI-nunchaku" → install, or

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

then restart. Then the backend wheel - the real inference engine - matched to your PyTorch/Python/CUDA. Use the pack's NunchakuWheelInstaller node to get the right one. Finally, download a quantized Flux model from nunchaku-ai: INT4 for RTX 20/30/40-series, NVFP4 for Blackwell 50-series, into models/diffusion_models.

Common issues & troubleshooting

"It's not actually loading my Flux." Because it's not that Flux. Nunchaku needs its own SVDQuant build; point it at the nunchaku-ai file, not your existing checkpoint or GGUF.

Node missing or import error. That's the wheel. Install the matching backend via NunchakuWheelInstaller and restart - the plugin nodes won't work without the engine behind them.

Fine on my 4080, broken on my 5080. INT4 and NVFP4 are separate downloads for separate GPU generations. Grab the one for your architecture.

LoRAs. Use NunchakuFluxLoraLoader / NunchakuFluxLoraStack from this same pack - Nunchaku applies LoRAs into the 4-bit model its own way, and that's the path that keeps the speed. Standard LoRA loaders aren't the move here.