ComfyUI –vram-headroom vs –reserve-vram: Why Your VRAM Limit Stopped Working After the Dynamic VRAM Update

If you updated ComfyUI in mid-2026 and suddenly found that your carefully tuned --reserve-vram 2 flag no longer keeps your GPU from maxing out, you are not alone. There is an open issue on the Comfy-Org tracker titled “--reserve-vram ignored” describing exactly this on an RTX 5090. The reason is not that the flag broke — it is that ComfyUI shipped a new memory subsystem and a new sibling flag, --vram-headroom, and the two now mean very different things.

This article explains what each flag actually does under the Dynamic VRAM system, how to diagnose which one you need, and how to stop ComfyUI from eating the last few gigabytes your desktop or browser still needs. Everything below is drawn from the official startup-flags reference and the Comfy-Org GitHub tracker; I have not run synthetic benchmarks, and I will not invent any.

What Changed: Dynamic VRAM Became the Default

ComfyUI’s Dynamic VRAM optimization — described in GitHub discussion #12699 — is now enabled by default on NVIDIA hardware (and ROCm 7.14+). Its whole job is to load and offload weights on demand instead of keeping everything resident, which is why it “massively reduces RAM usage and generally speeds things up” in the maintainers’ words.

The side effect is that a lot of older memory flags no longer behave the way they used to. The official startup-flags reference now says outright that --lowvram has “no effect when dynamic VRAM is enabled.” When you pair that with the older flags you relied on, the result is exactly the confusion people report after an update: a workflow that used to fit now blows past the limit, or a flag that used to reserve memory seems to do nothing.

Two flags matter most for capping VRAM, and they are easy to mix up:

• --reserve-vram GB — the older flag. Reserves VRAM for the operating system and other software.
• --vram-headroom GB — the newer flag, added alongside the Dynamic VRAM rework (PR #14480, 2026-06-15). Keeps extra VRAM free above the default headroom.

What –vram-headroom Actually Does

According to the startup-flags documentation, --vram-headroom GB (default 0) is the “extra VRAM in GB for dynamic VRAM to keep free above the default headroom.” The crucial detail is the last clause: ComfyUI “tries to keep this much VRAM completely free and unused, even counting VRAM used by other apps.”

That last point is what makes it different from --reserve-vram. --vram-headroom is designed for the scenario where ComfyUI is not the only thing on the card — you have a browser with hardware acceleration, a desktop compositor, OBS, or a second app that also needs VRAM. By setting, say, --vram-headroom 2, you tell the dynamic allocator to leave 2 GB genuinely free even after accounting for whatever other processes are already holding.

You launch it the same way as any other startup flag:

python main.py --vram-headroom 2

Or, on Windows Portable, add it to your .bat launcher (for example run_nvidia_gpu.bat) the same way you would any other argument.

Why –reserve-vram Seems Ignored Now

This is where the frustration kicks in. In open issue #15666, the reporter ran an RTX 5090 (31.5 GB) with --reserve-vram 2 and expected VRAM to never exceed 29.5 GB. Instead they observed the card hit 31.0 GB during model load and initialization, then “settle” to roughly 23.3 GB only after the run completed. Their conclusion — that --reserve-vram is effectively ignored during model load and initialization, then enforced afterward — mirrors what the maintainers and other commenters have begun to confirm.

One commenter on that thread summarizes the emerging picture well: --vram-headroom may actually allocate its headroom up front to avoid writing into it, which is why Windows can still report near-full VRAM even though ComfyUI is respecting the cap. Either way, the practical takeaway is the same — if your goal is to keep a hard slice of VRAM free during the worst-case moment (model load, when pressure is highest), --reserve-vram alone is no longer the reliable tool it used to be.

This is a moving target. The bug report is still open and assigned, so behaviors you read about today may change in the next point release. Treat the distinction below as “what the flags are documented to mean now,” not a promise that the underlying allocator has stopped surprising people.

How to Choose the Right Flag (and Verify It)

Start by deciding what problem you are actually solving, because the two flags address different ones:

• You want ComfyUI to leave room for other running apps (a browser, OBS, the desktop) → use --vram-headroom GB. This is the flag built for “I need 2 GB left over for the rest of my system.”
• You want to reserve VRAM for the OS on a headless or mostly-dedicated box → --reserve-vram GB still has a role, but understand its enforcement may be loose during model load under Dynamic VRAM.
• You need dynamic VRAM entirely out of the picture → --disable-dynamic-vram, which falls back to estimate-based loading. I covered the broken-workflow and TensorRT OOM aspect of this in a separate post on fixing Dynamic VRAM OOM and broken TensorRT nodes.

Once you pick a flag, do not trust your memory — verify with a live tool. On Linux, nvidia-smi in a second terminal shows per-process VRAM; on Windows, Task Manager’s GPU view or nvidia-smi in a terminal does the same. Watch the card during model load, not just after the generation finishes, because that is the moment the issue reporter saw the limit being violated.

A quick diagnostic sequence:

# 1. Baseline: what is already using VRAM before ComfyUI starts?
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

# 2. Start ComfyUI with your chosen flag
python main.py --vram-headroom 2

# 3. Watch peak usage during a real run, not an idle one
watch -n 1 nvidia-smi

If peak usage still climbs past your intended ceiling, the honest answer with the current codebase is to fall back to --disable-dynamic-vram and re-test, or to close the other VRAM consumer rather than fight the allocator.

Don’t Confuse This with Offloading or Pinned Memory

It is easy to lump every memory flag together, but they address different failure modes. --vram-headroom and --reserve-vram are about governing how much of the card ComfyUI is allowed to hold. They are separate from:

• Offload behavior — --lowvram, --novram, --gpu-only, which control where models live (and --lowvram is now a no-op under Dynamic VRAM).
• Pinned-memory OOM — a distinct video-model failure fixed with --disable-pinned-memory, which I documented in a separate article.
• System RAM pressure — the OOM-killer and swap problem, which is about host memory, not VRAM, and needs different handling.

Keeping these buckets separate is what prevents you from chasing the wrong flag for an hour while VRAM keeps climbing.

Conclusion

The short version: if you updated ComfyUI and your old --reserve-vram cap stopped holding, you are hitting a real, documented behavior change, not a typo in your launch command. The new --vram-headroom flag is the one explicitly designed to keep a hard slice of VRAM free above the default headroom while counting other apps’ usage — but even it has open questions around whether it allocates that headroom up front.

Before you change anything, decide which problem you have (leave room for other apps vs. reserve for the OS), apply the matching flag, and verify with nvidia-smi during model load rather than after the fact. And because this is an active area of the codebase — the --reserve-vram issue is still open and assigned — re-check the official startup-flags reference after your next update, because these two flags are exactly the kind of thing that changes between point releases.