HunyuanVideo Model Loader

This is where every graph built on kijai's Hunyuan wrapper starts: it loads the actual diffusion transformer - the checkpoint that turns your text embeds into frames - and hands out a HYVIDEOMODEL that the sampler, block-swap, LoRA, and torch-compile nodes all plug into.

Worth knowing up front: this is a wrapper around Tencent's original 13B HunyuanVideo, built by kijai (also the author of ComfyUI-WanVideoWrapper and ComfyUI-KJNodes) back when HunyuanVideo shipped in December 2024 with no native ComfyUI support at all. It was the fastest way to actually run the model. Native support arrived later, and by the wrapper's own changelog the author mostly stopped active development on it once that happened - he kept working only on the things native ComfyUI still doesn't do (context windowing, direct image-embed conditioning, manual memory management). If you're arriving here from an old tutorial, that's fine, it still runs - just know that HunyuanVideo itself has fallen a long way in local usage since early 2025, largely displaced by Wan. Mentions of this specific wrapper in the community peaked the month it launched and have been thin ever since.

The inputs that matter

• model - the checkpoint, picked from ComfyUI/models/diffusion_models. There's no auto-download for this one; you grab the single-file transformer from Kijai's own HunyuanVideo_comfy repo on HuggingFace and drop it in yourself.
• base_precision - bf16 by default, and that's the right call for nearly everyone.
• quantization - your VRAM lever. disabled runs full precision; the fp8_e4m3fn variants roughly halve the weight footprint at close to no visible cost, which is what makes this model fit on a consumer card at all. fp8_scaled is a special case - it only works with the official scaled fp8 weights Tencent released, not a generic fp8 cast, and it trades LoRA and fp8-fast support for quality closer to bf16.
• load_device - main_device by default, or offload_device to keep the model on CPU until it's actually needed.

Output is a single HYVIDEOMODEL.

The optional sockets

attention_mode defaults to flash_attn, which needs to be installed separately - if you haven't set that up, switch to sdpa, which works with zero extra setup on a reasonably current PyTorch and needs nothing else. sageattn is faster still but is its own install. compile_args (from HyVideoTorchCompileSettings), block_swap_args (from HyVideoBlockSwap), and lora (HYVIDLORA) bolt features on without needing a different loader for each. auto_cpu_offload is a simpler alternative to block swapping, borrowed from DiffSynth-Studio - less control over exactly how much VRAM you save, and can be slower, but it's one checkbox instead of tuning block counts. upcast_rope is on by default for accuracy; turning it off saves a little speed and memory if you're chasing every last bit.

How to install it

Via ComfyUI Manager: search ComfyUI-HunyuanVideoWrapper, install, restart. Manually:

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

then restart. That gets you the nodes. You still need, separately: the diffusion model above (into diffusion_models), the VAE (HyVideoVAELoader, into vae), and the LLM text encoder (DownloadAndLoadHyVideoTextEncoder, which does auto-download). None of that is optional - this is not a lightweight model.

Common issues & troubleshooting

The model dropdown is empty. No auto-download for this one - go grab a file from Kijai/HunyuanVideo_comfy on HuggingFace and put it in models/diffusion_models, then restart or rescan.

flash_attn errors on load. It isn't installed. Switch attention_mode to sdpa - it needs nothing extra and the README notes it works reliably as of recent PyTorch versions. Chase sageattn only once the rest of the graph is solid; it's the classic Triton-on-Windows headache.

Out of memory, even on a 24GB card. Expected - the README says outright not to expect to push resolution or frame count very high even at 24GB. Set quantization to an fp8 variant and attach a HyVideoBlockSwap node; that combination, plus a modest num_frames, is the standard way people get this running on consumer hardware at all.

fp8_scaled throws an error or looks worse than plain fp8. You need the specific official scaled fp8 weights for this mode, not just any fp8 file - check you downloaded the right one before assuming the setting is broken.