git:20260816.e017aec to git:20260819.9fe9ea3

---

name: triton-sageattention

description: Install Triton + SageAttention to accelerate ComfyUI (the sageattn attention_mode and inductor torch.compile used by WanVideoWrapper / many video graphs) — Windows-first (triton-windows + woct0rdho prebuilt SageAttention wheels matched to torch/CUDA/python into the RIGHT python), plus Linux (official triton + build) and Mac (N/A → sdpa/MPS). Critically also covers the SAFE sdpa / no-compile fallback so an example that assumes sageattn + torch.compile still runs when these aren't installed (video-extend TRAP 5). Use when a loader crashes with "No module named 'sageattention'" or reports triton unavailable, when asked to speed up Wan/video workflows, or when deciding whether to install acceleration vs. fall back.

globs:

- "**/*.json"

- "**/packs/**"

---

# Triton + SageAttention (ComfyUI acceleration)

> See also [`comfyui-launch-flags`](../comfyui-launch-flags/SKILL.md) for the full

> attention / VRAM / cache flag matrix. Note the **Z-Image exception**: Z-Image is

> broken under `--use-sage-attention` → launch it with

> `--use-pytorch-cross-attention` instead.

## Overview

Two **optional accelerators** that many modern video graphs (especially kijai's

**ComfyUI-WanVideoWrapper**) reference by default:

- **SageAttention** (`import sageattention`) — a quantized attention kernel.

Selected via a node's `attention_mode = sageattn` (WanVideoWrapper) or ComfyUI's

`--use-sage-attention` startup flag. ~20–40% faster sampling on supported NVIDIA

GPUs.

- **Triton** — the GPU kernel compiler that **inductor `torch.compile`** needs.

WanVideoWrapper's `WanVideoTorchCompileSettings` (and any `torch.compile`/

inductor node) compiles the model through Triton for another speedup.

> ⚠️ **The risk.** Both are **version-locked to your exact torch + CUDA + python**.

> A wrong wheel doesn't just fail to install — it can **break the torch install**

> (mismatched CUDA DLLs, `ImportError`, or silent NaNs). And the *failure mode of

> not having them* is a **hard crash before any sampling**:

> `ValueError: Can't import SageAttention: No module named 'sageattention'`, or

> compile errors / `triton: unavailable` in the startup log. This is exactly the

> [`video-extend`](../video-extend/SKILL.md) **TRAP 5**.

> ✅ **Therefore the default is: get a working render FIRST with the

> [sdpa / no-compile fallback](#the-safe-sdpa--no-compile-fallback-do-this-first),

> then OFFER to install acceleration for speed.** Never silently run a

> torch-breaking install to "fix" a workflow — fall back, render, *then* ask.

> ⚠️ **Verification note (June 2026).** Wheel sources, the triton↔torch table, and

> the live `attention_mode` enum below were verified against

> `woct0rdho/triton-windows`, `woct0rdho/SageAttention` releases, and

> WanVideoWrapper's nodes (see [Sources](#sources)). Versions move fast — **always

> re-read the live torch/CUDA/python first** (commands below) and pick the wheel

> that matches; flag anything you can't confirm rather than guessing.

---

## Decide first: do you even need them?

```

Workflow crashes "No module named 'sageattention'" ──┐

or "triton: unavailable" / torch.compile error ─┤

▼

1. APPLY THE SDPA / NO-COMPILE FALLBACK → render works now

▼

2. OFFER acceleration:

"Want me to install Triton + SageAttention for ~20–40%

faster sampling? It's a version-matched install that

touches your torch env — I'll verify torch/CUDA/python

first and can roll back."

▼

3. Only on YES → install per-OS below → verify → re-enable

sageattn + torch.compile in the workflow.

```

Mac (no CUDA): **skip the install entirely**, the answer is always sdpa/MPS.

---

## The safe sdpa / no-compile fallback (DO THIS FIRST)

When Triton/SageAttention aren't installed, make the workflow run **unaccelerated

but correct** by switching attention to **sdpa** (PyTorch's built-in scaled

dot-product attention — always available, no extra deps) and removing the

`torch.compile`/inductor wiring.

**WanVideoWrapper (the common case):**

1. On **every** `WanVideoModelLoader` set `attention_mode` → **`sdpa`**.

- Confirmed enum values: `sdpa`, `flash_attn_2`, `flash_attn_3`, `sageattn`,

`sparse_sage_attention`. The examples ship with `sageattn`; `sdpa` is the

universal safe one.

2. **Disconnect `WanVideoTorchCompileSettings`** from each loader's `compile_args`

input (or delete/bypass the node). No compile = no Triton needed.

3. (If present) bypass any `WanVideoSetRadialAttention` /

`sparse_sage_attention` node — those also route through SageAttention.

**Generic ComfyUI:** don't launch with `--use-sage-attention`; bypass any

`TorchCompileModel` / inductor node.

This costs you speed, not quality. Use `create_workflow (action:"modify")` / the panel's

strip-and-re-point flow to flip the widget and drop the link, then enqueue. Once

it renders, offer the install.

> Cross-ref: [`video-extend`](../video-extend/SKILL.md) documents this exact fix

> as TRAP 5 for the Pusa extension graph (both `WanVideoModelLoader`s →

> `attention_mode=sdpa`, disconnect `WanVideoTorchCompileSettings`).

---

## Windows install (the priority)

Windows has **no official Triton or SageAttention build**. You use community

prebuilt wheels, and **they must match torch + CUDA + python exactly**. The panel

agent has a shell (Bash for Claude / `exec` for Codex) — use it to run these in

the **correct python**, never the system `python`.

### Step 1 — find the RIGHT python (NOT system python)

ComfyUI on Windows comes in three flavors; each has its own python whose `pip` you

must target:

| Variant | Where its python lives | How to invoke pip |

|---|---|---|

| **Desktop (standalone)** | a `standalone-env\` (or `venv`) beside the install, e.g. `C:\Users\<you>\ComfyUI-Installs\ComfyUI\standalone-env\python.exe` | `"<install>\standalone-env\python.exe" -m pip ...` |

| **Portable** | `ComfyUI_windows_portable\python_embeded\python.exe` | `"<...>\python_embeded\python.exe" -m pip ...` |

| **Manual venv** | the venv you created (`venv\Scripts\python.exe`) | activate it, then `python -m pip ...` |

Detect it from the **live server** — the surest way to hit the same python ComfyUI

runs on:

- `install_comfyui (action:"environment")` / `get_system_stats` report `embedded_python` (true →

Portable), the python version and the `pytorch_version` (e.g. `2.10.0+cu130`).

- Inspect the running process's `argv` (from `get_system_stats`) — the path to

`main.py` reveals the install root; its sibling `standalone-env` / `python_embeded`

holds the python.

- Last resort, ask the user for their ComfyUI folder.

> ⚠️ Installing into the wrong python (e.g. a global `pip install`) is the #1

> Windows mistake: the package lands somewhere ComfyUI never imports from, so the

> loader still crashes "No module named 'sageattention'". Always use

> `"<that python>" -m pip`.

### Step 2 — read the installed torch + CUDA + python

Run with the python you just found:

```bash

"<python>" -c "import sys, torch; print(sys.version.split()[0], torch.__version__, torch.version.cuda)"

```

Example live output on this machine: `3.13.12 2.10.0+cu130 13.0` →

**python 3.13, torch 2.10, CUDA line cu130**. You'll pick wheels for that triple.

### Step 3 — install **triton-windows** (matched to torch)

Source: **`woct0rdho/triton-windows`** (the canonical Windows Triton fork; also on

PyPI as `triton-windows`). The pin is just an upper bound — pip resolves the right

build for your torch:

```bash

"<python>" -m pip install -U "triton-windows<3.7"

```

**Why `<3.7`:** each torch minor pins a Triton minor. Verified table:

| PyTorch | triton-windows | constraint to use |

|---|---|---|

| 2.7 | 3.3 | `"triton-windows<3.4"` |

| 2.8 | 3.4 | `"triton-windows<3.5"` |

| 2.9 | 3.5 | `"triton-windows<3.6"` |

| **2.10** | **3.6** | **`"triton-windows<3.7"`** |

(torch 2.6 or older → triton 3.2 or earlier.) Pick the row for *your* torch.

- **CUDA toolkit:** since `triton-windows 3.2.0.post11` a minimal CUDA toolchain

is **bundled in the wheel** — you do NOT need a separate CUDA Toolkit install for

Triton itself. (Triton 3.3–3.6 bundle the CUDA 12.8 line; works against cu12x/

cu13x torch.)

- **MSVC / vcredist:** Triton compiles C++ at runtime, so it needs the **MSVC

toolchain + "Visual C++ Redistributable 2015–2022"** present. A TinyCC is

bundled (since 3.2.0.post13) which covers many cases, but installing the

**Visual Studio Build Tools (C++ workload)** + latest vcredist is the reliable

fix if you hit compiler errors (see Traps).

- **Embedded/Portable python only:** the embedded distro ships without C headers,

so Triton can't compile. Download the matching `python_<ver>_include_libs.zip`

from the triton-windows releases and copy its **`include`** and **`libs`**

(note: `libs`, not `lib`) folders into `python_embeded\`. The Desktop

`standalone-env` usually already has these.

### Step 4 — install **SageAttention** (prebuilt wheel, matched to torch+CUDA)

**Strongly prefer the prebuilt wheel** — building from source needs the full CUDA

Toolkit (`nvcc`) + MSVC and frequently fails on Windows. Source:

**`woct0rdho/SageAttention` releases** (Windows wheels; v2 = SageAttention 2.x).

Latest verified tag: **`v2.2.0-windows.post5`**, with these four wheels (all

`cp310-abi3` → work on **python 3.10 through 3.13+** via the stable ABI; one wheel

covers all those pythons):

| Wheel filename | For |

|---|---|

| `sageattention-2.2.0+cu128torch2.9.1.post5-cp310-abi3-win_amd64.whl` | CUDA 12.8 line, torch 2.9.x |

| `sageattention-2.2.0+cu128torch2.10.0andhigher.post5-cp310-abi3-win_amd64.whl` | CUDA 12.8 line, torch ≥2.10 |

| `sageattention-2.2.0+cu130torch2.9.1.post5-cp310-abi3-win_amd64.whl` | CUDA 13.0 line, torch 2.9.x |

| `sageattention-2.2.0+cu130torch2.10.0andhigher.post5-cp310-abi3-win_amd64.whl` | **CUDA 13.0 line, torch ≥2.10** |

Pick by your **CUDA line** (`cu128` vs `cu130` — from `torch.version.cuda`: `12.8`

→ cu128, `13.0` → cu130) and **torch minor**. For the live machine above

(torch 2.10.0+cu130, py3.13) → the **last** wheel. Install by full URL:

```bash

"<python>" -m pip install "https://github.com/woct0rdho/SageAttention/releases/download/v2.2.0-windows.post5/sageattention-2.2.0+cu130torch2.10.0andhigher.post5-cp310-abi3-win_amd64.whl"

```

- The `cpXXX-abi3` tag means **one wheel works across python ≥ its base** (3.10+),

so py3.13 is covered even though there's no `cp313`-specific wheel — this is

expected, not a mismatch.

- **Always check the releases page for a newer tag** than `.post5` and newer torch

variants — the filename pattern is stable (`+cu<line>torch<minor>...abi3`).

- **Don't build from source** unless no wheel matches your torch/CUDA at all (then

you need CUDA Toolkit + MSVC; flag the cost to the user first).

### Step 5 — verify (Windows)

```bash

"<python>" -c "import triton; print('triton', triton.__version__)"

"<python>" -c "import sageattention; print('sageattention OK')"

"<python>" -c "import torch; print('torch still ok', torch.__version__, torch.cuda.is_available())"

```

All three must succeed **and torch must still import with CUDA** — if the third

line now fails, the install clobbered torch (see Traps → roll back). Then restart

ComfyUI and confirm the startup log no longer prints `Could not load

sageattention` / `triton: unavailable`. Finally re-enable in the workflow:

`WanVideoModelLoader.attention_mode = sageattn` and reconnect

`WanVideoTorchCompileSettings`, enqueue, and confirm it samples (a torch.compile

node will spend extra time on the **first** run compiling — that's normal).

---

## Linux install

Official builds exist here — much simpler:

```bash

# Triton: official, pip-installable; torch usually already pulls a matching triton.

pip install -U triton # or let torch's pinned triton stand; match torch minor

# SageAttention: pip, or build from source for your GPU arch

pip install sageattention # if a matching wheel exists for your torch/CUDA

```

- **Use the python that runs ComfyUI** (its venv/conda env) — same rule as Windows.

- **Version matching still applies:** torch pins a triton minor (e.g. torch 2.9.x

↔ triton 3.5.x, torch 2.10 ↔ 3.6); patch versions within a minor are

interchangeable. Don't `pip install triton` blindly if it would upgrade past

what your torch pins.

- **Build deps (if building SageAttention from source):** the **CUDA Toolkit with

`nvcc`** (matching your torch CUDA line), `gcc/g++`, and the torch headers. If

CUDA is in a nonstandard path, `export PATH=/usr/local/cuda-<ver>/bin:$PATH` so

the right `nvcc` is found. Building is GPU-arch specific and slow — prefer a

matching prebuilt wheel when one exists.

- Verify exactly as in Windows Step 5 (`import triton`, `import sageattention`,

torch still imports with CUDA).

---

## Mac

**Triton and SageAttention are N/A on Mac — there is no CUDA.** Do not attempt to

install them. Use **PyTorch sdpa** attention (the fallback above is the permanent

answer), which on Apple Silicon runs on the **MPS** backend. Set any

`attention_mode` to `sdpa`, never load `torch.compile`/inductor (Triton) nodes,

and run unaccelerated. If a workflow hard-requires `sageattn`, edit it to `sdpa`

rather than trying to satisfy the dependency.

---

## Verification checklist (any OS)

1. `import triton` succeeds and prints a version matching your torch (table above).

2. `import sageattention` succeeds.

3. **torch STILL imports** and `torch.cuda.is_available()` is `True` (the install

didn't break the env).

4. ComfyUI startup log: no `Could not load sageattention`, no `triton: unavailable`.

5. In the graph: `attention_mode = sageattn` loads without the `No module named

'sageattention'` ValueError; a `torch.compile`/`WanVideoTorchCompileSettings`

node completes its (slow) first-run compile and then samples.

6. A real render completes and looks correct (SageAttention can rarely introduce

NaN/noise on some GPUs — if output degrades vs. sdpa, fall back to sdpa).

---

## Traps

- **Wrong python / global pip.** Installing into system python (or the wrong

venv) means ComfyUI never imports it — the loader still crashes. Always

`"<that exact python>" -m pip`; for Portable that's `python_embeded\python.exe`,

for Desktop the `standalone-env\python.exe`. Verify with `pip show sageattention`

run by *that* python.

- **torch / CUDA / python wheel mismatch breaks torch.** Installing a `cu128` wheel

on a `cu130` torch (or a torch2.9 wheel on torch2.10) can drag in mismatched CUDA

DLLs and break `import torch` itself, or surface as a runtime DLL error. Match

`cu128`↔`12.x` / `cu130`↔`13.0` and the torch minor exactly. **Pin and verify:**

before installing, record `pip freeze | grep -i torch`; after, confirm torch

still imports with CUDA. If broken, **roll back** (`pip install

torch==<old>+cu<line> --index-url https://download.pytorch.org/whl/cu<line>`,

or uninstall the bad wheel) and re-apply the sdpa fallback.

- **Stale Triton cache after a torch/GPU/driver change.** Triton caches compiled

kernels in `~/.triton` (`%USERPROFILE%\.triton` on Windows). After upgrading torch,

swapping GPUs, a driver update, or a failed compile, that cache can go stale and

cause `torch.compile`/SageAttention runs to fail *even though the install is

correct* — recurring compile errors, `RuntimeError` in a Triton kernel, or a hang

on the first sample. **Fix: clear the cache and re-run** (Triton recompiles fresh):

```

# Windows

rmdir /s /q "%USERPROFILE%\.triton"

# macOS / Linux

rm -rf ~/.triton

```

Safe to delete — it's a pure cache. Do this BEFORE assuming the wheel is wrong

(it's a much cheaper fix than a reinstall/roll-back). If it recurs every run, the

install is genuinely mismatched (see the wheel-mismatch trap above).

- **MSVC missing (Windows Triton).** `torch.compile`/Triton errors like "Microsoft

Visual C++ ... required", `cl.exe not found`, or `PY_SSIZE_T_CLEAN`/DLL load

failures usually mean no MSVC toolchain. Install **Visual Studio Build Tools (C++

workload)** + the latest **"Visual C++ Redistributable 2015–2022"**; copying

`msvcp140.dll`/`vcruntime140*.dll` into the python folder is the documented

last-resort fix.

- **Embedded python has no headers.** Portable's `python_embeded` lacks

`include`/`libs`, so Triton can't compile and `torch.compile` fails. Copy the

matching `python_<ver>_include_libs.zip` `include` + **`libs`** (not `lib`)

folders from the triton-windows releases into `python_embeded\`.

- **py3.13 "no wheel" panic.** SageAttention's Windows wheels are `cp310-abi3` —

one wheel covers **py3.10–3.13+**. The absence of a `cp313` filename is *normal*;

do not conclude "no wheel for 3.13." (Source builds, by contrast, can genuinely

lag on the newest python — another reason to use the abi3 wheel.) Triton-windows

does ship py3.13-specific builds.

- **CUDA line confusion.** `torch.version.cuda` is the source of truth: `12.8` →

pick `cu128` wheels, `13.0` → `cu130`. Don't read the *system* CUDA driver

version — match what **torch** was built against.

- **"Install can break torch."** Treat every acceleration install as risky to the

env: get a working sdpa render first, capture the torch version, install,

re-verify torch, and be ready to roll back. Never leave the user with a broken

torch and no render.

- **SageAttention numerical artifacts.** On some GPUs (reported on H100/Hopper)

`sageattn` produces noise that `sdpa` doesn't. If a render looks worse than the

sdpa version, switch that workflow back to `sdpa` — correctness over speed.

- **First torch.compile run is slow.** Inductor compiles on the first sample

(tens of seconds to minutes); that's expected, not a hang. Subsequent runs are

fast. Don't "fix" it by ripping out compile unless it actually errors.

---

## See also

- [`video-extend`](../video-extend/SKILL.md) — **TRAP 5** is the canonical

example: the Pusa graph ships with `attention_mode=sageattn` +

`WanVideoTorchCompileSettings`; this skill is how you either satisfy or safely

fall back from that. Read its TRAP 5 for the exact node-by-node sdpa fix.

- [`troubleshooting`](../troubleshooting/SKILL.md) — "Torch / CUDA Version Errors"

and "Missing Nodes" sections for diagnosing a torch env that an install broke.

- [`installer-packs`](../installer-packs/SKILL.md) — packs note SageAttention/

Triton requirements in `pack.yaml` `notes`/`post_install`; acceleration is an

opt-in post-install step, never baked into a model download.

## Sources