Hunyuan 3 Soft Unload (Fast)

Here's the scenario that makes Hunyuan 3 Soft Unload (Fast) (class HunyuanImage3SoftUnload) the unloader I'd actually reach for: you're running Hunyuan, then Flux, then Hunyuan again - and a full unload/reload of a 45–80GB model takes minutes each way. Who wants that? Soft Unload doesn't delete the model. It parks it in CPU RAM and frees your VRAM, so the next Hunyuan run is a ~10–30 second restore instead of a ~2+ minute disk reload. The "Fast" in the display name is the whole pitch.

The tradeoff, and it's an important one: the model now lives in system RAM, holding 45GB+ of it. If your machine has 64GB of RAM and you're already offloading weights there, adding a soft-unloaded model on top can get tight. This node is for the swap it out and bring it back workflow, not the I'm done with Hunyuan forever workflow.

How it works

One action dropdown, three modes:

• soft_unload - move the model from GPU to CPU RAM, free the VRAM. This is the one you want.
• check_status - just reports where the model currently is, no action.
• restore_to_gpu - marked deprecated in the tooltip; the loader now handles restoring automatically. You can ignore it.

There's an optional trigger input (any type) and three outputs: success (BOOLEAN), status (STRING), and signal (wildcard) for sequencing.

The requirements - read these before you get burned

Soft Unload is not free, and the README is specific:

1. bitsandbytes >= 0.48.2 is required for quantized models. If you're on NF4 or INT8 and Soft Unload silently misbehaves, this is the first thing to check:

   pip install "bitsandbytes>=0.48.2"

2. The model must be loaded with offload_mode='disabled' (no meta tensors). It works with NF4, INT8, and BF16 - but it does not work with models loaded via device_map offloading, because those contain meta tensors that can't be parked the same way.

How to install it

Part of the Comfy_HunyuanImage3 pack:

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

Restart ComfyUI and hard-refresh the browser. Or search HunyuanImage in ComfyUI Manager.

Common issues & troubleshooting

It doesn't free anything. Check the bitsandbytes version first, then check whether your loader used device_map. Both conditions are in the README for a reason - this node's failure modes are almost entirely "prerequisite not met."

My RAM is exploding. Expected. A parked Hunyuan model is 45GB (NF4) to 80GB+ (BF16) of system RAM. This is not the node for RAM-constrained machines, and it's not the node for final cleanup - the README is blunt that Soft Unload "parks model in CPU RAM" and is "not for final cleanup (model stays in RAM)." For a real release, use plain Hunyuan 3 Unload or Force Unload.

I want to reload fast but the node won't restore. The loader handles the restore path in current versions; restore_to_gpu on this node is deprecated. Just queue your next Hunyuan generate and let the loader pull the parked model back.