DocKr / VRAM-Cleanup

What it is and why you'd bother

VRAM cleanup nodes are a genre ComfyUI users are rightly skeptical of. ComfyUI already manages memory on its own - it offloads models, empties caches, and generally keeps itself alive - so a node whose entire job is "free memory" has to justify its existence. DocKr / VRAM-Cleanup makes its case in one specific way: it's a scheduler. Instead of blasting your GPU memory free on every run, it fires ComfyUI's own cleanup internals every N executions, or the moment free memory gets tight. That's the gap ComfyUI's automatic model manager doesn't fill, because it decides what stays loaded by its own rules rather than your batch schedule. Long batch runs, multi-model video pipelines, workflows that chain a Q4 GGUF and a full-precision checkpoint - that's where this earns its keep.

How it actually works

The name is a half-truth, though, and it's worth knowing before you trust the emergency trigger. On every execution the node checks batch_index % batch_clear == 0. When that lands - or when free memory drops below critical_threshold_mb - it calls comfy.model_management.unload_all_models() (with offload_model on), then the classic triple whammy: gc.collect() three times, torch.cuda.empty_cache(), torch.cuda.ipc_collect(), and comfy.model_management.soft_empty_cache(). No voodoo; those are the exact calls you'd paste into a Python console. The scheduling is the feature. But the "critical" path is watching system RAM, not VRAM - critical_threshold_mb compares against psutil.virtual_memory().available. On a machine with plenty of RAM the emergency force-clean won't fire even if your GPU is full. Quirk, not bug, but it changes what that knob means.

The inputs that matter

The inputs you'll actually set:

• batch_clear - clean every N runs. Default is 60; the README's own recommendation is 10.
• batch_index - the current counter. The node's second output feeds right back into this for chaining.
• offload_model - the big one. True (the default) unloads every model, which means they fully reload on the next run. Every time it fires, you pay reload time.
• bypass_all - skip the clean for a run without deleting the node.
• critical_threshold_mb - emergency force-clean when free system RAM drops below this.

Outputs: anything (a true pass-through of any type, so you can drop this node inline in a graph without breaking wires) and batch_index (the counter, letting a downstream RAM-Cleanup chain off the same schedule).

Installing it

Install is trivial - one pack, no model files, a single dependency (psutil). ComfyUI Manager → search Comfyui_BatchClear_DocKr → install → restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/DocWorkBox/Comfyui_BatchClear_DocKr.git

What actually bites

The real gotchas aren't in the install; they're expectations. If VRAM never frees up, check your ComfyUI launch args before blaming the node: --highvram deliberately keeps models resident and no cleanup node overrides it - switch to --normalvram and let the node work as intended. Second, this node does not clear the execution cache. The menu's "Unload Models and Execution Cache" button does more, and people who've bench-tested a shelf of cleanup nodes will tell you that's the piece most of them miss - if a buggy node crashes on its second run due to cached state, this won't save you. Finally, the README's recommended settings (offload_model=False, batch_clear=10) are more conservative than the shipped defaults (offload_model=True, batch_clear=60). Start at 10, and leave offload_model off unless you're okay with a full reload cost on every clean.