/comfyui-launch-flags

name: comfyui-launch-flags
description: Pick the right ComfyUI startup flags for VRAM, attention, caching, and speed. The full decision matrix for OOM (--novram / --cache-none / --disable-smart-memory), shared-VRAM creep on Windows (--reserve-vram N), model-switching with big text encoders (--cache-none), high-VRAM throughput (--gpu-only / --highvram), and attention-backend selection (--use-sage-attention for speed, --use-pytorch-cross-attention as the highest-quality / Z-Image-safe fallback). Also the acceleration-stack + Blackwell/RTX 5000 (sm_120) notes. Use when a graph OOMs (especially long video like LTX 2 / WAN), when the GPU spills into shared VRAM and slows to a crawl, when switching between models eats all RAM, when Z-Image produces black/garbled output under Sage, or when deciding which attention backend to launch with. Flag names verified against upstream comfy/cli_args.py; see Sources.
globs:
  - "**/*.json"
  - "**/packs/**"

ComfyUI launch/performance flags

Overview

CLI flags passed to `main.py` control ComfyUI's runtime behavior (e.g. `python main.py --reserve-vram 2 --use-sage-attention`). The three that matter most for making a graph *run* rather than OOM or crawl are the VRAM strategy, the attention backend, and the cache mode. This skill is the decision matrix for choosing them.

> ⚠️ **Verification note (August 2026).** Every flag below was checked against > upstream [`comfy/cli_args.py`](https://github.com/comfyanonymous/ComfyUI/blob/master/comfy/cli_args.py) > on current master. ComfyUI adds/renames flags often — when in doubt run > `python main.py --help` in the target install and prefer that over this list. > **`--enable-triton-backend` / `--disable-triton-backend` ARE ComfyUI `main.py` > flags on master** (they used to be documented as SwarmUI-only; that is stale). > `--use-ck-attention` is kitchen INT8 attention — no `sageattention` wheel. > A June ComfyUI checkout still pins comfy-kitchen 0.2.10 and lacks > `--use-ck-attention`; `kitchen` action:"status" reports ComfyUI-side flag > support, not only the kitchen version. Use `kitchen` / `panel_kitchen` to see > what this GPU can actually run.

> How to apply today. The MCP's `restart_comfyui` (with `action: "start"`) > currently *replays the exact argv of the previous run*. It does not compose > fresh flags. So set these when you launch ComfyUI yourself (the > `python main.py …` line, a `run.bat`/shell alias, or the SwarmUI backend args > box), and the tool will preserve them on restart. Injecting flags through the > tool is a tracked follow-up.

---

Decide first: which flag do you need?

Symptom                                             ▶ Flag(s) to try
─────────────────────────────────────────────────────────────────────────────
CUDA out of memory, long video (LTX 2 / WAN)        ▶ --novram  (+ --cache-none)
OOM, still want models resident when they fit       ▶ --reserve-vram N  then --disable-smart-memory
GPU slows to a crawl, spills into "shared GPU        ▶ --reserve-vram 2..4
  memory" (Windows WDDM) mid-run
RAM blows up switching between models, or a huge     ▶ --cache-none
  text encoder (FLUX 2 / Mistral) won't unload
Plenty of VRAM (48GB+), want max throughput         ▶ --gpu-only  or  --highvram
Want faster sampling on NVIDIA                       ▶ --use-ck-attention if kitchen INT8 is available (skip the sage wheel); else --use-sage-attention
Z-Image produces BLACK / wrong output               ▶ --use-pytorch-cross-attention (NOT sage)
Sage gives black output on some models              ▶ --use-pytorch-cross-attention (or fix dtype)
ROCm, kitchen present, triton ≥ 3.7                  ▶ --enable-triton-backend

VRAM strategy and attention backend are each mutually exclusive groups, so pass at most one from each. You can combine one VRAM flag + one attention flag + one cache flag (e.g. `--novram --use-sage-attention --cache-none`).

---

VRAM strategy (mutually exclusive)

| Flag | What it does | Use when | |------|--------------|----------| | `--gpu-only` | Keep everything (incl. text encoders) on GPU | 48GB+ card, single model, max speed | | `--highvram` | Keep models resident in VRAM after use | High-VRAM card, repeated runs of one model | | *(default)* | ComfyUI's smart offload | Most setups — try this first | | `--lowvram` | Offload text encoders / parts to CPU | Mid card OOMing on load | | `--novram` | Extreme offload — minimal VRAM footprint | OOM on long video / huge models; pair with `--cache-none` | | `--cpu` | Everything on CPU (very slow) | No usable CUDA GPU only |

Modifiers (combine with the above):

• `--reserve-vram N` reserves N GB for the OS and other apps. It is the fix for the

Windows failure mode where the GPU quietly starts using shared VRAM and throughput collapses. Typical `2` to `4`; bump to `10` for heavy video decode.

• `--disable-smart-memory` forces aggressive offload to regular RAM instead

of keeping models cached in VRAM. Reach for this when a run gets *stuck* or OOMs intermittently. Slightly slower, much more reliable.

• `--async-offload` enables async weight offload streams (default on where

supported); `--disable-async-offload` turns it off if it misbehaves.

---

Attention backend (mutually exclusive)

| Flag | Notes | |------|-------| | `--use-ck-attention` | Comfy Kitchen INT8 attention. **No `sageattention` wheel.** Needs comfy-kitchen present and `int8_attention_is_available()` on this GPU. Prefer this over the sage wheel-matching install when `kitchen` action:"status" says INT8 is available. Restart required. | | `--use-sage-attention` | Quantized SageAttention kernel, ~20–40% faster sampling. Needs the `sageattention` package installed and version-matched — see [`triton-sageattention`](../triton-sageattention/SKILL.md). Skip this dance when `--use-ck-attention` is available. | | `--use-flash-attention` | FlashAttention kernels. Needs `flash-attn` built for your torch/CUDA. | | `--enable-triton-backend` / `--disabl