ComfyUI-VRAM-Manager

<table align="center"> <tr> <td align="center" bgcolor="#3478ca" width="88" height="36"><font color="#ffffff"><b>EN</b></font></td> <td align="center" bgcolor="#e5e7eb" width="88" height="36"><a href="zhmd/README.md"><font color="#4b5563"><b>中文</b></font></a></td> </tr> </table> <p align="center"> <img src="https://raw.githubusercontent.com/ussoewwin/ComfyUI-DistorchMemoryManager/main/icon.png" width="128"> </p>

ComfyUI-VRAM-Manager (formerly ComfyUI-DistorchMemoryManager) is an independent memory management custom node for ComfyUI. Provides Distorch memory management functionality for efficient GPU/CPU memory handling. Supports purging of SeedVR2, Qwen3-VL, Nunchaku models (FLUX/Z-Image/Qwen-Image), HSWQ, and Ollama server VRAM. Includes Model Patch Memory Cleaner for ModelPatchLoader workflows. Auto-detects non-PyTorch VRAM usage via NVML to prevent OOM errors in multi-process environments.

Overview

This custom node was created to address OOM (Out Of Memory) issues in video generation workflows like Upscaling with WAN2.2. The key point is that these OOM errors are caused by system RAM shortage, not VRAM shortage (can occur even on 64GB RAM systems depending on resolution and video length).

This is a completely original implementation designed specifically for Distorch memory management. Simply place it in the custom_nodes folder for easy installation and removal.

Features

General Manage VRAM (Startup Automatic Patch - New in v2.4.0)

<p align="center"> <img src="https://raw.githubusercontent.com/ussoewwin/ComfyUI-DistorchMemoryManager/main/png/generalvram.png" width="600"> </p>

• Description: A fully automated, GPU-wide VRAM headroom optimizer that runs seamlessly at ComfyUI startup. It automatically detects system-wide non-PyTorch VRAM usage (browsers, Discord, OBS, desktop window managers) via NVML and dynamically configures ComfyUI's VRAM management on load.

The Core Limitation of Standard ComfyUI

• PyTorch-Only Blind Spot: By default, ComfyUI can only recognize active VRAM allocations made within the PyTorch framework itself.
• The Problem: Standard ComfyUI is completely blind to physical VRAM consumed by external, non-PyTorch applications (such as web browsers, Discord, OBS, or desktop window managers). Because it cannot detect this external overhead, ComfyUI often overestimates available VRAM, resulting in sudden Out-Of-Memory (OOM) crashes when attempting to load heavy models.
• The Solution: This startup patch uses NVML to query the absolute physical VRAM usage of the GPU, calculating the exact difference between system-wide consumption and PyTorch's active memory. It then overrides ComfyUI's headroom limit (General Manage VRAM) with this real-world value to guarantee multi-process memory safety.

Key Benefits & Features

• Zero Node Setup: Operates entirely in the background at startup. No node placement in workflows, manual connections, or toggle switches are required.
• NVML-Powered Accuracy: Utilizes the pynvml (NVIDIA Management Library) API to query real-time physical GPU memory status, ensuring perfect accuracy.
• Auto-updated dependency: On every ComfyUI load (and via ComfyUI-Manager install.py), nvidia-ml-py is upgraded with pip install -U so the NVML binding stays current without a manual upgrade.
• Robust Multi-Process OOM Prevention: Dynamically patches ComfyUI's internal VRAM headroom buffer on load by calculating the exact difference between system-wide physical GPU usage and PyTorch allocations.
• Optimized for iGPU/dGPU Multi-GPU Setups:
  • Perfect for setups that offload Windows desktop rendering and browser acceleration to the CPU's integrated graphics (e.g., Ryzen 9 7900 built-in Radeon iGPU) and reserve the RTX GPU exclusively for CUDA workloads.
  • The startup patch detects extremely low non-PyTorch overhead (e.g., 0.02 GB), automatically shrinking the reserved chunk down from the default 0.68 GB to 0.02 GB to maximize ComfyUI's available memory.

---

Four Node Types

Model Patch Memory Cleaner (New in v1.2.0)

<p align="center"> <img src="https://raw.githubusercontent.com/ussoewwin/ComfyUI-DistorchMemoryManager/main/png/mpatch.png" width="400"> </p>

• Description: Memory cleaner specifically for ModelPatcher loaded model patches
• Features: Clears model patches loaded via ModelPatchLoader to prevent OOM during upscaling
• Input: Any data type (ANY) passthrough
• Output: Any data type (ANY) passthrough
• Options:
  • clear_model_patches: Clear model patches loaded via ModelPatchLoader (default: True)
  • clean_gpu: Clear GPU memory (default: True)
  • force_gc: Force garbage collection (default: True)
• Use Case: Place this node after using ModelPatchLoader (e.g., Z-Image ControlNet, QwenImage BlockWise ControlNet, SigLIP MultiFeat Proj) and before upscaling operations to prevent OOM errors. This node is designed for patch model format loaded via ModelPatchLoader, which is an exceptional format different from standard ControlNet models.
• Technical Details:
  • Detects ModelPatcher instances with additional_models or attachments containing model patches
  • Safely unloads model patches from VRAM
  • Performs cleanup_models_gc() to prevent memory leaks

General Purge VRAM V2 (v1.10, Enhanced in v1.2.0, v2.0.0, v2.2.0, v2.4.1, v2.4.2, v2.4.3)

<p align="center"> <img src="https://raw.githubusercontent.com/ussoewwin/ComfyUI-DistorchMemoryManager/main/png/pvram2.png" width="400"> </p>

• Description: Distortch suite node General Purge VRAM V2 (formerly LayerStyle LayerUtility: Purge VRAM V2; class id DisTorchPurgeVRAMV2) with enhanced model unloading, SeedVR2 / Qwen3-VL / Nunchaku purging, (v2.4.1) an HSWQ toggle for full HSWQ VRAM purge, (v2.4.2) an Ollama toggle below HSWQ for zero-residual Ollama server VRAM purge, and (v2.4.3) HSWQ Method 2c NVFP4 runtime pool / CUDA graph clear so a second ConvRot NVFP4 generation after purge does not hit quantize_nvfp4 / PyCapsule / pooled TC path failed
• Features: Same UI/behavior lineage as the LayerStyle original; keeps legacy workflows via class id DisTorchPurgeVRAMV2. Enhanced in v1.2.0 with more aggressive model unloading and improved error handling. Enhanced in v2.0.0 with Qwen3-VL and Nunchaku model purging support. Enhanced in v2.2.0 with Nunchaku SDXL model support. Enhanced in v2.4.1 with dedicated HSWQ purge pipeline (PinCache drain, PromptExecutor/SEGS in-place clear, HostUnregister, comfy_kitchen CUDA workspace reset). Enhanced in v2.4.2 with Ollama purge for comfyui-ollama and comfyui-ollama-describer (including describer's default keep_model_alive=-1). Enhanced in v2.4.3 with HSWQ Method 2c sys.modules scan for nvfp4_runtime and clear_nvfp4_runtime_pools() (in addition to kitchen workspace reset); prefers nodes/purge_vram.py; log prefix HSWQ INT8/NVFP4:. Supports SeedVR2 DiT/VAE, Qwen3-VL, Nunchaku (FLUX/Z-Image/Qwen-Image/SDXL), HSWQ (including NVFP4), and Ollama server unload.
• Input: Any data type (ANY) passthrough
• Options:
  • purge_cache: Run gc.collect(), flush CUDA caches, call torch.cuda.ipc_collect()
  • purge_models: Enhanced model unloading (v1.2.0):
    • Calls cleanup_models() to remove dead models
    • Calls cleanup_models_gc() for garbage collection
    • Marks all models as not currently used
    • Aggressively unloads models via model_unload()
    • Calls soft_empty_cache() if available
  • purge_seedvr2_models: Clear SeedVR2 DiT and VAE models from cache
    • Clears all cached DiT models from SeedVR2's GlobalModelCache
    • Clears all cached VAE models from SeedVR2's GlobalModelCache
    • Clears runner templates
    • Properly releases model memory using SeedVR2's release_model_memory()
  • purge_qwen3vl_models: Clear Qwen3-VL models from GPU memory (v2.0.0)
    • Searches for Qwen3-VL models in sys.modules and gc.get_objects()
    • Handles device_map="auto" case for multi-device models
    • Clears model parameters, buffers, and internal state
  • purge_nunchaku_models: Clear Nunchaku models (FLUX/Z-Image/Qwen-Image/SDXL) from GPU memory (v2.0.0, Enhanced in v2.2.0)
    • Supports NunchakuFluxTransformer2dModel, NunchakuZImageTransformer2DModel, NunchakuQwenImageTransformer2DModel, and NunchakuSDXLUNet2DConditionModel (v2.2.0)
    • Disables CPU offload before clearing models
    • Searches in sys.modules, ComfyUI current_loaded_models, and gc.get_objects()
    • Clears cache and temporary data attributes (v2.2.0)
    • Handles NunchakuSDXL wrapper class with diffusion_model access (v2.2.0)
  • HSWQ: Purge HSWQ residual GPU (and related host) memory — whole HSWQ path, not INT8-only (v2.4.1; NVFP4 Method 2c in v2.4.3)
    • Force-imports and drains HSWQ PinCache; clears PromptExecutor / SEGS caches in-place (does not call reset() mid-prompt)
    • Releases PINNED_MEMORY via HostUnregister where applicable
    • After core cleanup, resets comfy_kitchen CUDA workspace / empty-tensor caches (Method 2c) so reload (including INT8 GEMM) still works after purge
    • (v2.4.3) After kitchen reset, scans sys.modules for nvfp4_runtime and calls clear_nvfp4_runtime_pools() to clear HSWQ NVFP4 runtime pools / CUDA graphs
    • UI label is HSWQ; legacy workflow kwargs "HSWQ INT8" remain accepted; log prefix HSWQ INT8/NVFP4:
  • Ollama: Purge Ollama server VRAM loaded by comfyui-ollama and comfyui-ollama-describer (v2.4.2)
    • Toggle appears directly below HSWQ in the node UI (see screenshot above)
    • Targets describer's default keep_model_alive=-1 (model stays loaded until explicitly unloaded)
    • Harvests api_host / url from both custom-node packs; loops GET /api/ps until empty
    • Sends `/api/generate