Hunyuan 3 Loader (NF4 Low VRAM+)

This is the loader that makes the headline of this entire pack true. "Hunyuan 3 Loader (NF4 Low VRAM+)" is the version of the NF4 loader built for 24–32GB cards - the cards where the plain NF4 loader (everything on GPU, ~45GB) simply doesn't fit. The README calls the pairing of this node with the Low VRAM Budget generator "the recommended node pair for Low VRAM setups," and it's verified working on 24–32GB cards without bitsandbytes errors.

The trick is block swap. Instead of trying to pin the whole 4-bit model to the GPU, this loader keeps some transformer blocks on CPU and swaps them to the GPU during inference - the default of 20 swapped blocks keeps roughly 12 on the GPU and fits an RTX 3090/4090. Each NF4 block is only ~0.75GB, so swapping ten blocks buys you ~7.5GB of VRAM. Quality is untouched; only memory management changes.

The controls that matter

• blocks_to_swap - the headline knob, default 20. 20 is "good for 24GB GPUs"; set 0 to fall back to the legacy device_map loading path instead. Higher saves more VRAM, runs slower.
• gpu_memory_target_gb - the GPU budget for the NF4 weights: 18–20GB for a 24GB card, 26–28GB for 32GB. Only used in legacy mode (blocks_to_swap=0).
• reserve_memory_gb - headroom for inference activations, default 6GB. Also legacy-mode only; leave it ≥6.
• force_reload and the optional unload_signal round it out, and the output is the usual HUNYUAN_MODEL.

Note the honest framing in the tooltips: the budget sliders are "only used in legacy mode." In the default block-swap path, the loader manages memory automatically and the sliders exist for people who need the older device_map behavior.

The workflow it belongs to

The verified 24GB reference chain, straight from the README's screenshot:

Hunyuan 3 Loader (NF4 Low VRAM+) → Hunyuan Prompt Rewriter (optional) → Hunyuan 3 Generate (Low VRAM Budget) → Save/Display

The budget generator matches this loader's gpu_memory_target_gb (18–20GB) by leaving enough room for inference, and it adds the gpu_budget_gb override plus telemetry. On a 24GB test rig the author reports a working 1600×1600 render this way. Pair this loader with the plain Low VRAM generator if you don't need the budget telemetry - just don't pair it with the base Generate node, which assumes a fully-resident model.

Installing

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

Restart ComfyUI, or use ComfyUI Manager (search "Comfy_HunyuanImage3"). You need the NF4 weights in ComfyUI/models/:

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

The bitsandbytes>=0.48.2 requirement matters here - older versions were the source of the bitsandbytes validation errors this loader was specifically rebuilt to avoid.

Set expectations

"Runs on 24GB" and "runs well on 24GB" are different sentences. Community testers found NF4 with heavy CPU offload on a 4090 functional but slow - one described it as taking so long it wasn't worth the time, and a 12GB card is hopeless regardless of what you swap. This node removes the crash, not the PCIe bandwidth problem. It's the honest answer for the 24–32GB crowd; if you ever get access to a 48GB+ card, the plain NF4 loader is faster and simpler.