Hunyuan 3 Loader (NF4)

"Hunyuan 3 Loader (NF4)" is the simplest way to get Tencent's 80-billion-parameter HunyuanImage-3.0 into a ComfyUI graph. NF4 is a 4-bit quantization that shaves the model from ~160GB of BF16 weights down to roughly 45GB, and this loader keeps the whole thing on the GPU, no offloading games. If you have a 45–96GB card, this is the node you start with - it's the one the author benchmarks as the fastest configuration on a 96GB RTX 6000 Pro, and it's the default most example workflows assume.

How it works

The loader takes a model_name (it scans ComfyUI/models/ and reads extra_model_paths.yaml for the folder), loads the NF4 checkpoint via bitsandbytes, and hands you a HUNYUAN_MODEL to feed into any base-model generate node. force_reload busts the cache when you've got stale state; reserve_memory_gb is the knob that matters - VRAM left free for inference activations and VAE decode, default 6GB. Large images (>2MP) can eat ~15GB/MP, so bump it when you render big, or the generate node's own memory math will clamp your resolution before you get there.

There's also an optional unload_signal input (any type) - wire a trigger from downstream and the loader frees the model when you're done with it.

You need the actual NF4 weights, which the author pre-quantizes on Hugging Face. The v2 checkpoints have better block-swap defaults than the v1 run:

cd ComfyUI/models
huggingface-cli download EricRollei/HunyuanImage-3-NF4-v2 --local-dir HunyuanImage-3-NF4

The catch: which generate node to pair it with

This loader pins every quantized layer to the GPU. That means it expects the base Hunyuan 3 Generate - not the Large/Offload node (CPU offload hooks conflict with quantization) and not the Low VRAM generator (it's designed for device_map-offloaded models). The README's compatibility table is blunt about this: "Do not mix them." The matrix for this loader is simple - NF4 loader → base Generate for <2MP, and if the model doesn't fit, step down to the NF4 Low VRAM+ loader instead of trying to squeeze this one.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/EricRollei/Comfy_HunyuanImage3
cd Comfy_HunyuanImage3
pip install -r requirements.txt

Restart ComfyUI, or just use ComfyUI Manager and search "Comfy_HunyuanImage3". Note the dependency floor: bitsandbytes>=0.48.2 is what powers NF4 loading, and torch>=2.8.0 - if your environment is older, the loader will fail in cryptic ways. The author explicitly recommends PyTorch 2.9+ with CUDA 12.8 for the fastest Blackwell performance.

Reality check

Community testing found NF4 on a 24GB 4090 technically works - but only with the model spilling into system RAM, at which point generation slows to a crawl, and some testers wrote the whole thing off as not worth the time. The sweet spot for this specific loader (everything on GPU, fast) is a 48GB+ card. Below that, the Low VRAM+ variant is the honest answer. One more thing: the author's license on the integration code is CC BY-NC 4.0 - non-commercial. The model itself is Apache 2.0 from Tencent, but this pack's code is not free for commercial use without a separate license.