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` / `--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`](../z-image-txt2img/SKILL.md).
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`](../triton-sageattention/SKILL.md), 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`](../ltxv2-video/SKILL.md) / [`wan-t2v-video`](../wan-t2v-video/SKILL.md);
per-model VRAM math in [`troubleshooting`](../troubleshooting/SKILL.md) and
[`model-compatibility`](../model-compatibility/SKILL.md).

---

## 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`](../troubleshooting/SKILL.md).

## 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.