WanVideo Block Swap

If you've ever watched Wan 14B refuse to load on your 12 or 16GB card, this is the node that fixes it. Block swap moves transformer blocks out of VRAM and into system RAM, pulling each one back onto the GPU only when it's needed during the forward pass. You trade some speed for a dramatically lower VRAM ceiling - and for a lot of people it's the difference between running the good model and not running it at all.

It's a settings node: you configure how many blocks to swap and hand the resulting BLOCKSWAPARGS to the block_swap_args input on WanVideoModelLoader.

How it works

The Wan transformer is a stack of blocks (up to 40-48 depending on the model). Normally all of them sit in VRAM. With block swap, only a working subset stays resident; the rest live in CPU RAM and get streamed to the GPU on demand. More blocks swapped means less VRAM used but more back-and-forth over the PCIe bus, which is where the speed cost comes from. This is the same technique experienced users describe when they say things like "I swapped 24 Wan and 8 VACE blocks for this to fit comfortably in 32GB."

The inputs that matter

• blocks_to_swap - the main dial (default 20, max 48). More swapped = less VRAM, slower. The right number is "the fewest you can get away with." Start low, and if you OOM, raise it a few at a time until it fits.
• offload_img_emb / offload_txt_emb - also push the image and text embedding layers to CPU. Extra savings for when block swapping alone isn't enough on a really tight card.
• vace_blocks_to_swap (optional) - if you're running VACE, its blocks can be swapped separately. Handy because VACE adds its own memory on top of the base model.
• prefetch_blocks (optional) - prefetch upcoming blocks to hide some of the transfer latency. Can recover a bit of the speed you lose, at the cost of a little more VRAM headroom.

Output is a BLOCKSWAPARGS for the model loader.

How to install it

Ships with the pack. Via ComfyUI Manager: search WanVideo Wrapper, install, restart. Manually:

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

then restart. No model download - this just changes how the loaded model is placed in memory.

Common issues & troubleshooting

Still out of memory even with blocks swapped. Raise blocks_to_swap, turn on offload_img_emb and offload_txt_emb, and make sure the model loader is running an fp8 quantization. Block swap and fp8 are complementary - use both on a tight card. And make sure you have enough system RAM; the swapped blocks have to live somewhere, and 64GB is the community's comfort number for video work.

Generation got much slower. That's the trade. Every swapped block is a round trip to CPU RAM. If you swapped 40 blocks to be safe, back it off - swap only as many as you actually need to fit, and try prefetch_blocks to claw back some speed.

System RAM maxes out instead. You've pushed too much to CPU on a machine that can't hold it. Either add RAM, lower the swap count and accept the tighter fit via more aggressive fp8, or drop resolution/frame count.

Nothing changed. Confirm the BLOCKSWAPARGS output is actually wired into the model loader's block_swap_args input. A disconnected block-swap node does nothing.