<img width="895" height="610" alt="image" src="https://github.com/user-attachments/assets/dab15643-803c-4efd-a855-3403fde04ffa" />

ComfyUI-MemoryCleaner Usage Guide

Author: eddy
Project: ComfyUI-MemoryCleaner

Quick Start

For ComfyUI Node

1. Add "Memory Cleaner (Force)" node to your workflow
2. Place it after heavy operations (model loading, generation, VAE decode)
3. Connect your data flow through it
4. Run workflow

Recommended settings for heavy workloads:

aggressive_trim: ✓ True
enable_privileges: ✓ True
external_helper: ✓ True
skip_trim_if_c_low: ✓ True
min_c_free_gb: 60.0
purge_standby: ✗ False (unless running as admin)

For Standalone Scripts

Check memory:

python cleanup_ram.py --check

Clean memory:

python cleanup_ram.py

Trim specific process (e.g., ComfyUI):

# Auto-detect
python ram_trim_target.py --auto

# Or target PID
python ram_trim_target.py --pid 12345

Understanding the Cleanup Process

What Happens During Cleanup?

1. Model Unloading (0/7):

   • Unloads models from VRAM to system RAM
   • Clears model cache
   • Cleans up model patches
   • Requests aggressive memory free from ComfyUI

2. Python GC (1-3/7):

   • Collects unreferenced Python objects
   • Frees Python heap memory
   • Runs 3 passes for thorough cleanup

3. PyTorch Cache (4/7):

   • Empties CUDA cache
   • Collects IPC memory
   • Resets memory statistics

4. OS-Level Trimming (5/7) - THE KEY STEP:

   • Checks C: drive free space
   • Enables Windows privileges if possible
   • Calls EmptyWorkingSet - forces pages to disk
   • Calls SetProcessWorkingSetSize(-1, -1) - shrinks working set
   • If fails, uses external helper script for cross-process cleanup
   • This is what frees 30-45GB

5. CUDA Sync (6/7):

   • Synchronizes all GPU operations
   • Ensures cleanup is complete

6. Final GC (7/7):

   • One last pass to catch anything missed

7. Optional Standby Purge:

   • Clears Windows standby lists
   • Requires administrator privileges

Common Scenarios

Scenario 1: Heavy Model Workflow (SDXL, Flux, WanVideo)

Problem: Loading large models fills RAM to 50-60GB, subsequent operations OOM.

Solution:

Load Model A → Generate → Memory Cleaner → Load Model B → Generate
                          [Free 40GB]

Settings:

• aggressive_trim=True
• external_helper=True
• min_c_free_gb=60 (ensure C: has space for pagefile)

Expected: 30-45GB freed after each cleanup.

Scenario 2: Batch Processing Loop

Problem: Each batch iteration accumulates memory, crashes after 5-10 iterations.

Solution:

Loop Start → Process Batch → Memory Cleaner → Loop End
                             [Clean each iteration]

Settings:

• aggressive_trim=True
• skip_trim_if_c_low=True (safety)

Expected: Stable memory across hundreds of iterations.

Scenario 3: Low C: Drive Space

Problem: C: drive has <30GB free, cleanup causes disk full error.

Solution 1 (Recommended): Move pagefile to D/E drive

• System Properties → Advanced → Performance → Virtual Memory
• Set C: to small fixed size (2-4GB)
• Set D: to system-managed or large fixed size

Solution 2: Disable OS trim

aggressive_trim=False

Settings:

• skip_trim_if_c_low=True
• min_c_free_gb=100 (high threshold)

Note: Without OS trim, cleanup effect is limited (1-2GB vs 30-45GB).

Scenario 4: Running as Non-Admin

Problem: EmptyWorkingSet: ✗ FAILED (err 6), privileges not available.

Solution: External helper automatically activates!

What happens:

1. Process-internal WinAPI calls fail
2. Node detects failure (returns None)
3. Spawns ram_trim_target.py --pid <current> as external process
4. External process has better privilege context
5. Successfully frees 30-45GB

No action needed: Fallback is automatic.

Parameter Reference

aggressive_trim (BOOLEAN, default=True)

Enable: Full OS-level memory trimming with WinAPI calls
Disable: Only Python GC + CUDA cleanup (1-2GB effect)

When to disable:

• C: drive critically low (<20GB free)
• Running on non-Windows OS (Linux/macOS don't support WinAPI)
• Debugging workflows (faster iteration)

enable_privileges (BOOLEAN, default=True)

Enable: Try to enable SeIncreaseQuotaPrivilege and SeDebugPrivilege
Disable: Skip privilege elevation

Note: Even if fails, external helper provides fallback.

external_helper (BOOLEAN, default=True)

Enable: Use ram_trim_target.py for cross-process cleanup (recommended)
Disable: Only use process-internal WinAPI calls

Why enable:

• Higher success rate (95%+ vs 50%)
• Better privilege context
• Proven 39.51GB cleanup in testing

skip_trim_if_c_low (BOOLEAN, default=True)

Enable: Check C: free space before trimming (safety)
Disable: Always trim regardless of disk space (DANGEROUS)

Critical: Keep enabled unless you know pagefile is on another drive.

min_c_free_gb (FLOAT, default=20.0)

Default 20GB: Basic safety margin
Recommended 60GB: Safe for heavy workloads
100GB+: Ultra-safe for production

Calculation:

• OS trim moves memory to pagefile.sys
• If trimming 40GB, pagefile grows by ~40GB
• Set threshold = expected trim amount + 20GB buffer

purge_standby (BOOLEAN, default=False)

Enable: Purge Windows standby memory lists
Disable: Skip standby purge

Requirements:

• Administrator privileges
• Windows only

Effect:

• Frees standby/modified page lists
• Minimal impact on pagefile (unlike OS trim)
• FlushModifiedList: 0 (success)
• PurgeStandbyList: -1073741727 (needs admin)

Monitoring Effectiveness

Check Logs for These Indicators

Good cleanup (30-45GB):

[5/7] C-level aggressive cleanup...
      Working Set Before: 50.350 GB
      Using external helper to trim working set...
      ✓ External helper freed 42.120 GB

💾 CLEANUP RESULTS:
  Process RAM freed: 42.100 GB

Limited cleanup (1-2GB):

[5/7] Skipping OS trim: C:\ free 15.2 GB < 60.0 GB (avoid pagefile growth)

💾 CLEANUP RESULTS:
  Process RAM freed: 1.234 GB

Failed then recovered:

[5/7] C-level aggressive cleanup...
      EmptyWorkingSet: ✗ FAILED (err 6)
      SetProcessWorkingSetSize: ✗ FAILED (err 6)
      Using external helper to trim working set...
      ✓ External helper freed 39.510 GB

System-Level Verification

Before cleanup:

python cleanup_ram.py --check
# Shows: 50-60GB used, <10GB available

After cleanup:

python cleanup_ram.py --check
# Shows: 10-20GB used, 40-50GB available

Troubleshooting

"C: drive keeps filling up"

Symptom: After cleanup, C: drive loses 30-40GB space.

Root cause: OS trim moves memory to pagefile.sys on C:.

Solutions:

1. Increase min_c_free_gb to 60-100
2. Move pagefile to D/E drive (recommended)
3. Disable aggressive_trim temporarily

"No memory freed"

Symptom: "Process RAM freed: 0.000 GB" or negative values.

Possible causes:

1. C: drive guard active: Check logs for "Skipping OS trim"
   • Solution: Free up C: drive or move pagefile
2. Privileges failed: Check "Privileges: ... = NO"
   • Solution: Should auto-fallback to external helper
3. Memory actively in use: Models still loaded
   • Solution: Ensure models are unloaded before cleanup node

"External helper not available"

Symptom: "External helper not available or failed."

Causes:

1. ram_trim_target.py missing
   • Solution: Reinstall or check file exists
2. Python interpreter not found
   • Solution: Check sys.executable path
3. Timeout (>60s)
   • Solution: System too slow, increase timeout in code

"Privileges always = NO"

Symptom: "Privileges: SeIncreaseQuotaPrivilege=NO, SeDebugPrivilege=NO"

Impact: Process-internal WinAPI calls may fail (err 6).

Mitigation: External helper provides automatic fallback.

Optional: Run ComfyUI as administrator for better privileges.

Best Practices

✅ DO

1. Place at workflow end: After all operations complete
2. Monitor C: drive: Keep 50-100GB free
3. Enable external helper: Best success rate
4. Set high min_c_free_gb: 60GB+ for heavy workloads
5. Check logs: Verify "freed" values are substantial
6. Use in loops: Clean each iteration to prevent accumulation

❌ DON'T

1. Don't clean after every node: Overhead adds up
2. Don't disable safety guards: skip_trim_if_c_low protects you
3. Don't ignore C: drive warnings: Pagefile can fill disk
4. Don't set min_c_free_gb too low: <20GB risks disk full
5. Don't enable purge_standby without admin: Will fail silently
6. Don't expect miracles on Linux/macOS: WinAPI only works on Windows

Performance Metrics

Typical Results (Windows, Heavy Workflow)

| Metric | Before | After | Improvement | |--------|--------|-------|-------------| | Process RAM | 50.3 GB | 8.2 GB | -42.1 GB | | System RAM | 60.1 GB | 18.3 GB | -41.8 GB | | VRAM | 28.5 GB | 0.08 GB | -28.4 GB | | C: Free | 45 GB | 45 GB | No change (good) | | Time | - | 2.3s | Fast |

Lightweight Results (No OS Trim)

| Metric | Before | After | Improvement | |--------|--------|-------|-------------| | Process RAM | 10.5 GB | 9.2 GB | -1.3 GB | | VRAM | 8.5 GB | 0.5 GB | -8.0 GB | | Time | - | 0.5s | Very fast |

Advanced: Direct Script Usage

cleanup_ram.py

# Check only
python cleanup_ram.py --check

# Output:
# Process RAM: 50.35 GB
# System RAM: 60.12 / 63.85 GB (94.2%)
# TOP 10 MEMORY-CONSUMING PROCESSES:
#   1. python.exe    50.35 GB (PID: 12345)
#   ...

ram_trim_target.py

# Auto-detect ComfyUI
python ram_trim_target.py --auto

# Output:
# Target PID: 12345  Name: python.exe
# Steps:
#   open            : ok
#   EmptyWorkingSet : ok
#   SetPWS          : ok
# WorkingSet Before: 50.35 GB
# WorkingSet After : 8.23 GB
# Freed            : 42.12 GB

purge_standby.py (Admin Required)

# Run as administrator
python purge_standby.py

# Output:
# FlushModifiedList           : OK (status 0x00000000)
# PurgeLowPriorityStandbyList : OK (status 0x00000000)
# PurgeStandbyList            : OK (status 0x00000000)

Getting Help

Issues: Report on GitHub with logs and system info
Questions: Include ComfyUI version, OS, memory specs
Logs: Copy full cleanup output from console

---

Author: eddy
Repository: ComfyUI-MemoryCleaner
License: Apache License 2.0