HunyuanVideo BlockSwap

HunyuanVideo officially wanted 45 to 60GB of VRAM at launch. The README for this pack is blunt about the reality on consumer hardware: "memory use is entirely dependent on resolution and frame count, don't expect to be able to go very high even on 24GB." Block swap is the main lever that makes running this model on a normal GPU possible at all - it moves transformer blocks out of VRAM into system RAM, streaming each one back to the GPU only when the forward pass actually needs it. You trade some speed (PCIe transfer is roughly an order of magnitude slower than GPU memory bandwidth) for a much lower VRAM ceiling.

This is a settings node: configure how much to swap, then wire the output into HyVideoModelLoader's block_swap_args input.

The inputs that matter

• double_blocks_to_swap - default 20, which is also the max. That's worth calling out: out of the box, this pack already swaps every double block by default. If you have VRAM to spare and want more speed, this is a value you'd lower, not raise - most tutorials assume you're fighting for headroom, but if your card is comfortable, dial this down first.
• single_blocks_to_swap - default 0, max 40. This is your second lever once double blocks are maxed and you're still tight. HunyuanVideo's transformer has more single-stream blocks than double-stream ones, so there's a lot of room here if you need it.
• offload_txt_in / offload_img_in (both default off) - push the text and image embedding layers to CPU too. Smaller savings, but useful for squeezing the last bit out of a genuinely tight card.

Output: block_swap_args, into the model loader.

How to install it

Ships with the pack - nothing separate to download for this node.

• ComfyUI Manager - search ComfyUI-HunyuanVideoWrapper, install, restart.
• Manual - cd ComfyUI/custom_nodes && git clone https://github.com/kijai/ComfyUI-HunyuanVideoWrapper, then pip install -r ComfyUI-HunyuanVideoWrapper/requirements.txt, restart.

No model file for this node - it only changes how an already-loaded model is placed in memory.

Common issues & troubleshooting

Still out of memory with double_blocks_to_swap already maxed at 20. Start raising single_blocks_to_swap - that's where the remaining headroom lives, up to 40. Combine with fp8 quantization on the model loader; block swap and fp8 are complementary, not alternatives, and this pack is exactly the kind of heavyweight model where you want both stacked.

Generation is much slower than you expected. That's the fundamental trade - every swapped block is a round trip over PCIe, which the community has clocked at roughly an order of magnitude slower than GPU memory bandwidth. If you're not actually VRAM-constrained, this is the node to back off first, since the default already swaps the maximum number of double blocks.

System RAM fills up or the process crashes outside the GPU. The swapped blocks have to live somewhere - if your system RAM is also tight, block swap doesn't have anywhere to put them. Watch total system memory, not just VRAM, especially if you're also running the LLM text encoder on the same machine.

Reported OOM crash even with reasonable settings on an 8GB card. This model genuinely does not fit comfortably on low-VRAM hardware even with block swap maxed - people have hit hard crashes on 8GB cards regardless of frame count or step settings. If you're on 8-12GB, keep resolution and frame count conservative from the start rather than relying on block swap alone to bail you out.