u5dev-comfyUI_u5_VramFREE/docs/en

u5_FreeVRAM - ComfyUI Memory Management Node

Advanced memory management and VRAM optimization custom node for ComfyUI. Existing memory release nodes never quite worked for me, so I built a fresh one.

日本語 | 中文

📋 Table of Contents

• Overview
• Features
• Installation
• Basic Usage
• Sequential Loaders
• Best Practices
• Parameter Reference
• System Requirements
• Troubleshooting
• License
• Acknowledgements

---

Overview

u5_FreeVRAM optimizes memory usage inside ComfyUI workflows so you can run complex graphs on limited VRAM.

In short, it lets you free and reload VRAM at arbitrary points in your workflow.

---

Primary Use Cases

• Complex workflows: Execute multiple model types sequentially inside one workflow (line art → coloring, etc.)
• Batch processing: Prevent memory leaks during long runs
• SaaS environments: Clear caches on shared GPUs

---

Features

This custom node ships with two main feature sets.

1. FREE VRAM Node

Provides VRAM cleanup utilities.

Cleanup actions:

• Model unload: Release loaded models from memory
• GPU cache clear: Flush CUDA caches to reclaim VRAM
• Execution cache clear: Purge the ComfyUI execution cache
• Garbage collection: Collect unused Python objects

Smart execution:

• Threshold skip: Skip processing when free VRAM already meets the threshold
• Async wait: Detect a safe timing to release memory automatically

2. Sequential Loaders

Load models sequentially to minimize VRAM usage.

Normally model loaders have no inputs and all run in parallel at the start of a workflow. These loaders can be inserted mid-graph instead.

Available loaders:

• Sequential Checkpoint Loader: Sequentially load checkpoint files
• Sequential LoRA Loader: Sequentially load LoRA files
• Sequential CLIP Loader: Sequentially load CLIP models (supports safetensors and every CLIP type)
• Sequential VAE Loader: Sequentially load VAE models (supports safetensors and TAESD variants) ※Not compatible with GGUF (I tried!)

Highlights:

• Uses only built-in ComfyUI features (no extra dependencies)
• Execution order controlled by the trigger input

---

Installation

1.Clone the repository into your custom_nodes folder.

git clone "https://github.com/u5dev/comfyUI_u5_VramFREE.git"

2. Restart ComfyUI.

---

Basic Usage

The nodes appear under the u5 category in the node menu.

FREE VRAM Node

Insert the node anywhere in your workflow to clear memory.

How to use:

# As a relay node
[Any node] → [FREE VRAM] → [Next node]

Parameters:

• Any (input, optional): Pass-through input that accepts any data type
  • Works unconnected: Can be placed at the start of the workflow
  • When connected: Forwards the incoming data to the output unchanged
• MinFreeVRAMGB (optional): Skip cleanup when free VRAM is already above this value (default: 0.0)
  ※Freeing VRAM is asynchronous, so the value is approximate.

Outputs:

• Bypass(Relay): Tunnels the input data (returns None when no input is provided)

---

Sequential Loaders

Sequential Loaders expose a trigger input; they wait for the previous node to finish before loading. Whatever arrives at trigger is forwarded to the Bypass(Relay) output socket.

Refer to the workflow examples below for practical wiring.

---

Best Practices

1. Clearing caches in SaaS environments

Use case: Ensure the previous user's cache is gone on shared GPUs

[Start Workflow]
    ↓
[FREE VRAM (MinFreeVRAMGB=0.0)] ← Force a cleanup
    ↓ trigger
[Sequential Checkpoint Loader] ← Load after freeing
    ↓ (MODEL, CLIP, VAE)
[CLIP Text Encode (Prompt)]
    ↓ (CONDITIONING)
[KSampler]
    ↓ (LATENT)
[VAE Decode]
    ↓ (IMAGE)
[Save Image]

Key points:

• Place FREE VRAM right after the workflow starts
• Force cleanup by setting MinFreeVRAMGB=0.0
• Use Sequential Loaders to guarantee execution order

2. Running multiple models on low VRAM (≤8 GB)

Use case: Two-pass SDXL image2image pipeline

1st pass drafts a base (img2img preview) with light settings.
2nd pass secures memory through FreeVRAM, then loads Checkpoint → LoRA → VAE sequentially for the final render.

Key points: Shared: encode positive/negative prompts once and feed both samplers.

1st pass: prepare img2img source → resize to 1024x1024 → VAE Encode → KSampler (draft) 　　↓ 2nd pass: route the latent through the FreeVRAM gate as the trigger 　　↓ Sequential Checkpoint Loader (final checkpoint) 　　↓ Sequential LoRA Loader (apply multiple LoRA) 　　↓ KSampler (※pass the latent via bypass into the sampler) 　　↓ Sequential VAE Loader (final VAE) 　　↓ VAE Decode 　　↓ Save Image

※The first pass finds a good seed; the second loads LoRA and a different VAE sequentially while Free VRAM keeps pressure under control.

---

Parameter Reference

FREE VRAM Node

Parameter	Type	Required	Default	Description
Any	ANY	✗ (optional)	None	Pass-through input; accepts any data type and works even when disconnected
MinFreeVRAMGB	FLOAT	✗ (optional)	0.0	Skip cleanup when free VRAM already exceeds this threshold (in GB)

Outputs:

• Bypass(Relay): Returns the input as-is (or None when empty)

Sequential Checkpoint Loader

Parameter	Type	Default	Description
ckpt_name	COMBO	-	Checkpoint file name
trigger	ANY	None	Optional trigger input for execution order

Outputs:

• MODEL, CLIP, VAE, Bypass(Relay)

Sequential CLIP Loader

Parameter	Type	Default	Description
clip_name	COMBO	-	CLIP file name (.safetensors)
type	COMBO	stable_diffusion	CLIP type (stable_diffusion, qwen_image, etc.)
trigger	ANY	None	Optional trigger input for execution order

Outputs:

• CLIP, Bypass(Relay)

Supported CLIP types:

• stable_diffusion (SD 1.x/2.x)
• stable_cascade (Stable Cascade)
• sdxl (SDXL)
• sd3 (SD3)
• flux (Flux)
• qwen_image (Qwen2-VL)
• etc.

Sequential VAE Loader

Parameter	Type	Default	Description
vae_name	COMBO	-	VAE file name (.safetensors/.pt) or TAESD variant
trigger	ANY	None	Optional trigger input for execution order

Outputs:

• VAE, Bypass(Relay)

Supported VAE:

• Standard safetensors VAEs
• TAESD variants: taesd, taesdxl, taesd3, taef1

Sequential LoRA Loader

Parameter	Type	Default	Description
model	MODEL	-	Incoming MODEL
clip	CLIP	-	Incoming CLIP
lora_name	COMBO	-	LoRA file name
strength_model	FLOAT	1.0	Strength applied to the model
strength_clip	FLOAT	1.0	Strength applied to CLIP
trigger	ANY	None	Optional trigger input for execution order

Outputs:

• MODEL, CLIP, Bypass(Relay)

---

System Requirements

Required

• ComfyUI: Latest version recommended
• Python: 3.8 or later
• PyTorch: The version bundled with ComfyUI
• GPU: CUDA-capable GPU recommended (CPU mode works)

Optional

• psutil 5.8.0+: Detailed system memory metrics

  pip install psutil
  

Recommended

• VRAM: Enough to run a KSampler in ComfyUI
• RAM: Same as above
• OS: Any OS that can run ComfyUI

---

Troubleshooting

Memory is not being freed

Causes and fixes:

1. MinFreeVRAMGB is set too high

   • Check current free VRAM: nvidia-smi
   • Test with MinFreeVRAMGB=0.0 to force a cleanup

2. Another process uses the GPU

   • Verify there are no other ComfyUI instances
   • Disable browser hardware acceleration
   • Close GPU-intensive applications

3. ComfyUI execution cache remains

   • Use "Free model and cache" in ComfyUI Manager
   • Restart ComfyUI

Sequential Loaders do not run

Causes and fixes:

1. Forgot to wire trigger

   • Make sure every trigger input/output is connected
   • One missing connection breaks the execution order

2. Import error

   • Inspect the console log
   • Restart ComfyUI
   • Reinstall the custom node

3. File not found

   • Confirm model files live in the expected folders

Important log messages (ComfyUI console):

• [FreeVRAM] Sequential Loaders loaded successfully - Loaded correctly
• VRAM FREE (u5): Cleared: Models, Cache, GC | Freed: X.XX GB - Cleanup succeeded

---

License

See the LICENSE file for details.

---

Acknowledgements

This project relies on:

• ComfyUI - node-based UI framework
• PyTorch - deep learning framework

---

Version: 1.0.0
Last Updated: 2025-09-30
Author: u5dev