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 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. 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 / --disable-triton-backend	Enable or disable the comfy-kitchen triton backend. ComfyUI master flags (not SwarmUI-only). ROCm hosts with kitchen + triton ≥ 3.7 want --enable-triton-backend. Restart required.
--use-pytorch-cross-attention	PyTorch SDPA. Highest quality, always available, no extra deps. The safe default and the correct fallback.
--use-split-cross-attention / --use-quad-cross-attention	Memory-optimized math attention for older/low-VRAM cards.

Two gotchas worth memorizing:

1. Z-Image + Sage = broken. Z-Image (Turbo/Base) does not sample correctly under --use-sage-attention; you get black or garbled output. Launch Z-Image with --use-pytorch-cross-attention instead. See z-image-txt2img.
2. Sage black output on other models. If a model outputs black only with Sage, either switch to --use-pytorch-cross-attention, or (SwarmUI) set Advanced Sampling → Preferred DType = Default (16-bit). Sage-on vs Sage-off also produces slightly different images, so expect non-identical seeds.

When a graph hard-crashes with No module named 'sageattention' / triton: unavailable, the fix is the sdpa / no-compile fallback in triton-sageattention, not this flag.

---

Cache mode (mutually exclusive)

Flag	Effect
(default --cache-ram)	Cache results under RAM pressure
--cache-classic	Aggressive result caching
--cache-lru N	Keep at most N node results (LRU)
--cache-none	Cache nothing — re-executes every node; lowest RAM/VRAM. Essential when switching between dual models or when a giant text encoder (FLUX 2's Mistral) must fully unload.

---

Speed / precision

• --fast enables experimental, potentially quality-degrading optimizations. Accepts specific PerformanceFeature values: fp16_accumulation, fp8_matrix_mult, cublas_ops, autotune. Bare --fast turns them all on. Test output quality before committing to it.
• UNet/VAE/text-encoder dtype casts exist too (--fp8_e4m3fn-unet, --fp16-unet, --bf16-unet, --fp32-unet, …) for forcing a compute precision. Usually the model or loader picks the right one, so only reach for these to work around a specific dtype error.

---

Recommended combos (recipes)

Long video OOM (LTX 2 / WAN, 24GB):   --novram --cache-none
                                      (add --disable-smart-memory if it stalls)
Windows shared-VRAM creep:            --reserve-vram 3
FLUX 2 / huge text-encoder swaps:     --cache-none
High-VRAM throughput (48GB+):         --gpu-only        (or --highvram)
Fast NVIDIA sampling (most models):   --use-ck-attention   (if kitchen INT8 is available)
                                      --use-sage-attention (otherwise; needs the wheel)
Z-Image (any):                        --use-pytorch-cross-attention
ROCm + kitchen + triton ≥ 3.7:        --enable-triton-backend

Cross-refs: video OOM specifics in ltxv2-video / wan-t2v-video; per-model VRAM math in troubleshooting and model-compatibility.

---

Acceleration stack & GPU coverage (context)

The attention/compile accelerators are version-locked to your exact torch + CUDA + Python. A mismatched wheel doesn't just fail to import; it can break the torch install. A known-good, mutually-compatible stack for late-2025 / 2026 NVIDIA (including Blackwell / RTX 5000, sm_120) looks like:

Component	Role	Notes
Torch + CUDA	base	e.g. Torch 2.9.x on CUDA 12.8/13; use the wheel index matching your driver
Triton	torch.compile / inductor	Windows: triton-windows (woct0rdho)
SageAttention	--use-sage-attention	wheel matched to torch/CUDA/python
FlashAttention	--use-flash-attention	built per torch/CUDA/python
xFormers	memory-efficient attention	optional
InsightFace	FaceID / IP-Adapter / ReActor	onnxruntime-gpu alongside

Operational facts worth carrying:

• No system-wide CUDA toolkit is required to run ComfyUI. An up-to-date NVIDIA driver plus prebuilt wheels is enough. A full CUDA/MSVC/cuDNN toolchain is only needed to compile kernels yourself.
• For broad arch coverage when building wheels, TORCH_CUDA_ARCH_LIST=7.5;8.0;8.6;8.9;9.0;10.0;12.0+PTX spans RTX 20xx→50xx and datacenter (A100/H100/B200). +PTX lets newer archs JIT.
• DeepSpeed has no wheels for Python 3.13, and several accel wheels lag the newest Python. 3.10 to 3.12 is the safe range for the full stack.
• Clear the Triton cache (~/.triton / %USERPROFILE%\.triton and temp) when you hit stale-kernel Triton errors after an upgrade.
• Prefer uv pip install over pip for the venv. Resolves and downloads are dramatically faster. install_comfyui already supports this via preferUv.
• A single bad custom node can crash all of ComfyUI at startup. Install and test acceleration and new node packs on a fresh/known-good install, not before a deadline. See troubleshooting.

Quantization quick take

• FP8-scaled (per-tensor scaled) is markedly higher quality than plain base FP8, ~half the size of BF16, and usually faster.
• Prefer FP8-scaled over GGUF when you have enough system RAM. ComfyUI's block-swap streams from RAM, so BF16/FP8 can run on 24GB GPUs given ample RAM. Fall back to GGUF (Q8→Q4) only when RAM is the constraint.
• NVFP4 / NVFP8 are markedly faster on Blackwell (RTX 5000) at near-BF16 quality for supported models; LoRA support on NVFP4 is still partial.

---

Sources

• Official: ComfyUI CLI args at https://github.com/comfyanonymous/ComfyUI/blob/master/comfy/cli_args.py (--use-ck-attention, --enable-triton-backend, --disable-triton-backend, --fast); hardware gates in comfy/model_management.py (supports_fp8_compute SM ≥ 8.9, supports_nvfp4_compute / supports_mxfp8_compute SM ≥ 10.0); kitchen backends in the comfy-kitchen README https://github.com/Comfy-Org/comfy-kitchen
• Empirical: operational flag/stack recipes distilled from community auto-installer changelogs (SECourses); flags cross-checked against upstream above. The SwarmUI-only note for --enable-triton-backend is retracted as of ComfyUI master.