SeedVR2 BlockSwap Config

SeedVR2 is the best detail upscaler the open-source community has right now, and for a long time it was also famous for one thing: dumping an out-of-memory error on you halfway through. BlockSwap is the reason that reputation faded. It's the knob that lets a model that wants a 24GB card squeeze onto your 12GB or 8GB one, at the cost of some speed. If you googled this node, you almost certainly hit an OOM and want to know how to make it stop. This is the answer.

Here's the trick, and it's a genuinely clever one. A diffusion transformer is a stack of dozens of near-identical blocks that run one after another. You don't need all of them on the GPU at once - you only need the block that's computing right now. So BlockSwap keeps the active blocks in VRAM and parks the rest in ordinary system RAM, streaming each one back onto the GPU just before it's needed and evicting it after. Your model effectively runs out of a much smaller VRAM footprint than its size suggests. The catch is obvious once you say it out loud: shuttling weights across the PCIe bus every step is slower than leaving them on the card. More blocks swapped, more VRAM saved, more time spent. That's the whole trade.

The inputs that matter

This is a config node - it doesn't process anything itself. It bundles your settings into a single block_swap_config output (the node's only output) that you wire into the DiT model-loading side of the SeedVR2 pipeline. One input carries the weight:

• blocks_to_swap (default 16, range 0–36) - the dial. 0 disables swapping entirely (fastest, needs the most VRAM). 16 is the balanced starting point the node itself recommends. Crank toward 32 (the 3B model's ceiling) or 36 (the 7B model's) for maximum savings and maximum slowdown. Start at 16, and only climb until the OOM stops.

The rest are worth knowing but you'll rarely touch:

• offload_io_components (default off) - pushes the embedding and I/O layers to CPU too, for a bit more headroom when blocks alone don't get you there. Slower again. Flip it on only if you're still short after maxing blocks_to_swap.
• use_non_blocking (default on) - lets those GPU transfers happen asynchronously. Leave it on; it's free performance.
• cache_model (default off) - keeps the model resident in RAM between runs so a batch of images doesn't reload it every time. Handy for directory processing, pointless for a single upscale.
• enable_debug (default off) - prints the actual per-phase memory and timing numbers. Turn this on the first time you're tuning; the real VRAM savings depend on your model and it'll show you them instead of making you guess.

How to install it

BlockSwap ships inside the SeedVR2 pack, so you install the whole thing once. Easiest path is ComfyUI Manager: open Custom Nodes Manager, search ComfyUI-SeedVR2_VideoUpscaler, install, restart. Manual works too:

cd ComfyUI/custom_nodes
git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler

then install its requirements.txt with ComfyUI's Python and restart. The SeedVR2 models themselves download automatically to ComfyUI/models/SEEDVR2 the first time you run an upscale, so there's nothing extra to fetch for BlockSwap to work.

Common issues & troubleshooting

You maxed blocks_to_swap and it still OOMs. BlockSwap only relieves the upscaling (DiT) stage. If the crash lands during "Decoding," that's the VAE, and no amount of block swapping touches it - you need VAE tiling on the VAE loader node instead. Turn on enable_debug and read which phase actually blows up before you chase the wrong fix.

Grid-like seams in the output. That's almost never BlockSwap - it's the quant. Plain FP8 SeedVR2 models are known to stamp a tiling grid onto the image, and the community fix is switching to a mixed_block35 FP8 variant (or FP16 if it fits). Don't burn an afternoon on swap settings for an artifact that swap didn't cause.

On a Mac, the option just turns itself off. That's intentional. Apple Silicon uses unified memory, so GPU and CPU already share one pool and swapping between them buys nothing. The node disables itself with a warning rather than pretending.