Hunyuan Instruct Loader

"Hunyuan Instruct Loader" loads the Instruct family of HunyuanImage-3.0 - the variant that adds built-in prompt enhancement, chain-of-thought reasoning, image editing, and multi-image fusion, all on-device, no external LLM API required. It's the pack's fanciest model family, and this node is the gatekeeper that figures out which Instruct model you have, how it's quantized, and how to fit it on your card.

The Instruct models come in two flavors, and you need to understand the difference before you pick one:

• Instruct (full) - 50-step inference with CFG. Highest quality, slowest.
• Instruct-Distil - 8-step inference, CFG-distilled. The README claims ~6× faster at "same quality." This is why the default model_name is the Distil INT8 variant.

Both come in BF16, INT8, and NF4. That's six checkpoints in the family, and the loader auto-detects the quant type and the Distil-vs-full split from the folder name.

The inputs that matter

• model_name - scans ComfyUI/models/ (plus extra_model_paths.yaml). The default points at the Distil-INT8 download; you'll see whatever Instruct folders you've dropped in.
• blocks_to_swap - the VRAM lever. NF4 fits on a 48GB card with 0 swapped; INT8 and BF16 on 96GB want 20–28 swapped. The tooltip gives exact block sizes: NF4 ~0.75GB/block, INT8 ~2.5GB/block, BF16 ~5GB/block. For full (non-Distil) INT8, the tooltip recommends 10–15 swapped to leave 40GB+ for the CFG dispatch mask and KV cache.
• vram_reserve_gb - default 30, auto-boosted to 40 for full Instruct (which doubles all inference tensors under CFG). Ignored when block swap is active; no effect on NF4. Raise to 40–50 if you OOM during generation.
• attention_impl - sdpa (default) or flash_attention_2 (needs the flash-attn package).
• moe_impl - eager (default) or flashinfer (faster, needs flashinfer installed).
• moe_drop_tokens - default true; drops tokens that exceed expert capacity for lower VRAM at a ~1–3% quality cost. Set false on ≥48GB cards for best quality.
• vae_dtype - bfloat16 default; float32 reduces banding on smooth gradients.

Output: a single HUNYUAN_INSTRUCT_MODEL that feeds the Instruct Generate / Image Edit / Multi-Fusion nodes. The Instruct loader is not interchangeable with the base loaders - different output type, and mixing them errors out.

Downloading the models

Pre-quantized v2 weights from the author's Hugging Face (Distil-INT8 is the recommended 96GB pick):

cd ComfyUI/models
huggingface-cli download EricRollei/HunyuanImage-3.0-Instruct-Distil-INT8-v2 --local-dir HunyuanImage-3.0-Instruct-Distil-INT8-v2

If your models live on another drive, add the folder to extra_model_paths.yaml under a hunyuan_instruct: key, or the loader won't see them.

Installing

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

Restart ComfyUI (or ComfyUI Manager, search "Comfy_HunyuanImage3"). One dependency gotcha: transformers>=4.47 with 5.x supported via runtime patches - if you're on an old transformers and things behave oddly, update it.

Where people get burned

The Instruct models need trust_remote_code=True because they ship custom model code - the loader handles this automatically, so don't fight it. Also: RAM accumulates across successive loads (the author lists it as a known issue; a restart is the reliable fix). And block swap only exists if blocks_to_swap > 0 - setting 0 disables it entirely, which on a 96GB card with an INT8 or BF16 Instruct model means you simply won't fit. If your first Instruct run OOMs and you never touched that slider, that's the reason.