<h1 id="comfyui-sageattention-installer">ComfyUI SageAttention Installer</h1>GitHub - <a target="_blank" rel="ugc" href="https://github.com/kernel-panic-0/comfyui-sageattention-installer">https://github.com/kernel-panic-0/comfyui-sageattention-installer</a>An easy to use bash TUI script that installs <a target="_blank" rel="ugc" href="https://github.com/thu-ml/SageAttention">SageAttention</a> into an existing ComfyUI installation on Ubuntu 24.04 (other distros may work but are untested).By default it installs SageAttention 2, compiled from source against your local CUDA toolkit. An interactive menu (or <code>--sa-version</code>) also offers SageAttention 3 (FP4 kernels, Blackwell-only) and SageAttention 1 from PyPI.<blockquote>Why source-only for v2/v3? PyPI's <code>sageattention</code> package only ships SageAttention 1.x (latest 1.0.6). SageAttention 2 and 3 were never published to PyPI — they must be built from the <code>thu-ml/SageAttention</code> repository. The old "install the prebuilt wheel first" behaviour of this script silently installed SageAttention 1; that path has been removed.</blockquote>Both standard <code>pip</code>/<code>venv</code> setups and <code>uv</code>-managed ComfyUI installs are supported (auto-detected).<h2 id="choosing-a-version">Choosing a version</h2>Option What it is Needs <code>1</code> Triton-only kernels, PyPI wheel (<code>sageattention==1.0.6</code>) nothing extra <code>2</code> (default) CUDA kernels, built from source CUDA toolkit (nvcc) + C++ compiler <code>3</code> FP4 kernels (<a target="_blank" rel="ugc" href="https://github.com/thu-ml/SageAttention/tree/main/sageattention3_blackwell">sageattention3_blackwell</a>), built from source Blackwell GPU (sm_100 / sm_120 / sm_121), CUDA ≥ 12.8, Python ≥ 3.13, torch ≥ 2.8, einops, internet (the build shallow-clones CUTLASS)SageAttention 3 installs as a separate package (<code>sageattn3</code>), so it coexists with v1/v2 rather than replacing them. The script refuses to build v3 on a non-Blackwell GPU or with nvcc &lt; 12.8 (upstream's <code>setup.py</code> rejects both anyway — this just fails fast with a clearer message).<h2 id="prerequisites">Prerequisites</h2>Before running the script, make sure you have:<ul><li>Ubuntu 24.04 on x86_64 (other distros may work but are untested).</li><li>An NVIDIA GPU with working drivers (<code>nvidia-smi</code> runs).<ul><li>Ampere (RTX 30), Ada (RTX 40), Hopper (H100) and Blackwell (RTX 50 / sm_120, B200 / sm_100) are recommended. Pre-Ampere cards will run but see little/no benefit.</li></ul></li><li>ComfyUI already installed (the script does not install ComfyUI itself), with a CUDA build of PyTorch (<code>torch&gt;=2.3.0</code>) inside its environment.</li><li>Triton (<code>triton&gt;=3.0</code>) — the script will offer to install/upgrade it.</li><li>git (<code>sudo apt install git</code>).</li><li>For SageAttention 2 (the default): a CUDA toolkit (nvcc) whose major version matches the CUDA your PyTorch was built against.</li><li>For SageAttention 3: see the table above.</li><li>sudo (optional) — only used to install missing system packages (e.g. <code>build-essential</code>) when you agree to the prompt.</li></ul><h3 id="about-the-cuda-toolkit">About the CUDA toolkit</h3>SageAttention 2 and 3 must be compiled with <code>nvcc</code>. If no toolkit is found the script tells you and offers to install Ubuntu's package.Be aware of a common Ubuntu 24.04 trap:<ul><li><code>sudo apt install nvidia-cuda-toolkit</code> installs CUDA 12.0.1 and puts <code>nvcc</code> at <code>/usr/bin/nvcc</code> (no <code>/usr/local/cuda</code> symlink). This is usually too old — it mismatches modern PyTorch builds, fails the per-arch CUDA floors (Ada fp8 ≥ 12.4, Hopper fp8 ≥ 12.3, Blackwell ≥ 12.8), and is hard-rejected for SageAttention 3 (needs ≥ 12.8).</li><li>For a matching toolkit, prefer NVIDIA's CUDA apt repo: <code>https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/</code> (install <code>cuda-keyring</code>, then e.g. <code>sudo apt install cuda-toolkit-13-0</code>), or use the official <code>.run</code> file from the CUDA Archive.</li></ul><h2 id="usage">Usage</h2><pre><code>chmod +x install_sageattention2.sh
./install_sageattention2.sh</code></pre>The script is interactive by default: it asks which version to install (2 is the default — just press Enter), annotates whether your GPU supports SageAttention 3, then confirms the ComfyUI directory, the Python environment and any missing dependencies before building.<h3 id="flags">Flags</h3><pre><code> --comfyui-dir PATH ComfyUI directory (default: ~/ComfyUI)
 --sa-version {1|2|3} SageAttention major version (default: 2)
 2 = CUDA kernels, built from source (recommended)
 3 = FP4 kernels, Blackwell only (sm_100/sm_120/
 sm_121); needs CUDA &gt;= 12.8, Python &gt;= 3.13,
 torch &gt;= 2.8; installs the 'sageattn3' package
 1 = Triton-only PyPI wheel (sageattention 1.0.6)
 --from-source Kept for compatibility — v2 is always built from
 source now
 --max-jobs N Parallel compile jobs for the source build (default: nproc)
 -y, --non-interactive Accept all defaults, never prompt
 -h, --help Show help and exit
</code></pre>Environment: <code>CUDA_HOME</code> overrides toolkit detection; <code>CC</code>/<code>CXX</code> (both required) override host-compiler selection — otherwise the system <code>gcc</code>/<code>g++</code> is used and snap-confined compilers are never chosen automatically.Example — fully non-interactive, SageAttention 2:<pre><code>./install_sageattention2.sh --comfyui-dir ~/ComfyUI -y</code></pre>Example — SageAttention 3 on an RTX 50:<pre><code>./install_sageattention2.sh --sa-version 3</code></pre>Example — SageAttention 1 instead:<pre><code>./install_sageattention2.sh --sa-version 1</code></pre>Example — source build with 16 parallel jobs:<pre><code>./install_sageattention2.sh --max-jobs 16</code></pre><h2 id="what-it-does">What it does</h2><ol><li>Locates ComfyUI (flag value → prompt → default <code>~/ComfyUI</code>).</li><li>Detects the Python environment — <code>uv</code> if a <code>uv.lock</code> or <code>[tool.uv]</code> table is present, otherwise a standard venv (<code>.venv</code>/<code>venv</code> next to ComfyUI).</li><li>Checks dependencies — git, NVIDIA driver, Python ≥ 3.9, PyTorch ≥ 2.3.0 (CUDA build), Triton ≥ 3.0 (offers to install/upgrade), and detects your GPU's compute capability (used for the SageAttention 3 support check).</li><li>Asks which version to install (TUI menu, default 2) and shows whether your GPU is supported by SageAttention 3.</li><li>Inspects the CUDA toolkit (v2/v3 only) — looks for <code>nvcc</code> in <code>/usr/local/cuda-*</code>, <code>/usr/local/cuda</code>, <code>/usr</code> and <code>$CUDA_HOME</code>, warns about version mismatches and the per-arch CUDA floors (Blackwell sm_120 needs ≥ 12.8), and offers to install Ubuntu's package if nothing is found.</li><li>Installs SageAttention:<ul><li>v2/v3: verifies a C++ compiler exists (offers <code>apt install build-essential</code>), installs the Python build deps (<code>ninja</code>, <code>setuptools</code>, <code>wheel</code>, <code>packaging</code>, <code>pybind11</code>), then runs a toolchain probe before the real build — a trivial C++ file compiled against torch's dev headers plus a one-line nvcc host-compiler check. This catches, up front: torch installs that ship no dev headers (stripped "portable" bundles — the script offers to reinstall PyTorch from the official wheel index), sandboxed compilers (e.g. snap clang cannot read <code>/mnt</code>, <code>/media</code> or host <code>/tmp</code>), and nvcc rejecting the host compiler (offers <code>gcc-12</code>). For v3 it additionally enforces the upstream gates (Blackwell GPU, nvcc ≥ 12.8) and checks <code>einops</code> before building. The build itself is a regular <code>pip install . --no-build-isolation --no-deps</code> (not editable) with <code>MAX_JOBS</code> and — for v2 — the README speed flags <code>EXT_PARALLEL=4</code>, <code>NVCC_APPEND_FLAGS="--threads 8"</code> (v3's setup.py tunes nvcc itself). v3 builds from the repo's <code>sageattention3_blackwell/</code> subdirectory. If the build still fails, the log is scanned for known missing-dependency patterns, the fix is offered, and the build can be retried (up to 3 attempts). The full log is kept in <code>sageattention_build.log</code> next to wherever you ran the script.</li><li>v1: <code>pip install sageattention==1.0.6</code> — no compilation.</li></ul></li><li>Runs a smoke test — calls <code>sageattn(q, k, v)</code> (or <code>sageattn3_blackwell(q, k, v)</code> for v3) on a small CUDA tensor to confirm the kernel actually runs (not just that the import works).</li><li>Prints a summary and how to enable it in ComfyUI.</li></ol><h2 id="launching-comfyui-with-sageattention">Launching ComfyUI with SageAttention</h2><pre><code>cd ~/ComfyUI
# venv install:
./venv/bin/python main.py --use-sage-attention
# uv install:
uv run python main.py --use-sage-attention</code></pre>SageAttention 3 is different: ComfyUI's core <code>--use-sage-attention</code> flag targets SageAttention 1/2. To use v3, select it per-model with the KJNodes Patch Sage Attention KJ node (<code>sageattn3_fp4_cuda</code> mode) or a dedicated SageAttention3 custom node:<pre><code>from sageattn3 import sageattn3_blackwell
attn_output = sageattn3_blackwell(q, k, v, is_causal=False)</code></pre>If you use the ComfyUI Desktop app, don't pass the flag on the command line - enable SageAttention in the ComfyUI settings UI instead.<h2 id="troubleshooting">Troubleshooting</h2>"SageAttention 3 supports Blackwell GPUs only". v3's FP4 kernels only exist for compute capabilities 10.0 (B200), 12.0 (RTX 50) and 12.1. On anything older, install SageAttention 2 instead."SageAttention 3 requires a CUDA toolkit &gt;= 12.8". Install a newer toolkit from NVIDIA's repo (see About the CUDA toolkit above). Note Ubuntu 24.04's <code>nvidia-cuda-toolkit</code> apt package (12.0.1) can never satisfy this.Build fails with <code>'torch/extension.h' file not found</code> (or <code>ATen/...</code>, <code>pybind11/...</code>) even though the <code>-I</code> paths in the log look correct. Either your torch install ships no development headers — common with stripped-down "portable" torch bundles or environments copied between machines/drives (dangling symlinks) — or the compiler is sandboxed: snap clang cannot read <code>/mnt</code>, <code>/media</code> or the host <code>/tmp</code>, so every include under those paths fails. The script's toolchain probe detects both before building and offers to fix them (reinstall torch / switch to <code>/usr/bin/g++</code>). The script never auto-selects a compiler that resolves under <code>/snap</code>.nvcc fails with "unsupported GNU version" / "unsupported clang version". Your host compiler is newer than the CUDA toolkit supports. The script offers to install <code>gcc-12</code>/<code>g++-12</code> and use them as the host compiler."No CUDA toolkit found" / nvcc errors. Your toolkit version probably doesn't match the CUDA PyTorch was built against. Check <code>nvcc --version</code> against the "CUDA" line in the script's summary, and install a matching toolkit from NVIDIA's repo (see About the CUDA toolkit above). Blackwell GPUs (RTX 50, compute capability 12.0) need CUDA ≥ 12.8.<code>ModuleNotFoundError: No module named 'triton'</code> when launching ComfyUI. Triton wasn't installed in the ComfyUI environment. Re-run the script (it will detect the missing Triton and offer to install it), or manually run <code>pip install triton</code> (≥ 3.0) in the same environment ComfyUI uses.Runtime smoke test fails after a successful build. Usually a CUDA/CUDA-toolkit mismatch or a too-old GPU. Re-check the toolkit version and your GPU compute capability against the floors in Prerequisites.uv environment not detected. The script looks for <code>uv.lock</code> or a <code>[tool.uv]</code> table in <code>pyproject.toml</code>. If your uv project is structured differently, run with <code>--comfyui-dir</code> pointing at the directory that contains those files.Spaces in the ComfyUI/venv path. The v1 wheel path handles spaces fine. The v2/v3 source builds do not support spaces in the venv/Python path — if you hit this, relocate your venv to a space-free path, or use SageAttention 1.<h2 id="license">License</h2>See <a target="_blank" rel="ugc" href="https://github.com/kernel-panic-0/comfyui-sageattention-installer/blob/main/LICENSE">LICENSE</a>.

Files with SHA256: 483fa90755ef094f00f2a3e02a6f493b712849cf3b1062a192fea2bb10a20859