build(deps): install Triton on Windows NVIDIA installs (#9993)

Author: Pfannkuchensack

docs/src/content/docs/configuration/Optimization/sage-attention.mdx

@@ -50,7 +50,9 @@ smaller (not measured).
   InvokeAI has measured it on an RTX 4090; the other generations use the kernels SageAttention picks for them, which
   InvokeAI has not validated (on RTX 30-series cards, its Triton kernel). Jetson Orin is not supported.
 - **SageAttention 2.2, installed separately.** InvokeAI was validated with 2.2.0. The `sageattention` package on PyPI is
-  the older SageAttention 1 and is not used. On Windows it also needs the `triton-windows` package.
+  the older SageAttention 1 and is not used.
+- **Triton**, which InvokeAI's NVIDIA install on Windows x64 and Linux includes (on Windows the `triton-windows`
+  package). A [manual install](/start-here/manual/) on Windows without the `cuda` extra has none; see below.
 - Not available on AMD (ROCm), Apple Silicon (MPS), Intel (XPU) or CPU. There InvokeAI keeps PyTorch's attention.
 
 ## Installing
@@ -63,20 +65,21 @@ commands use [uv](https://docs.astral.sh/uv/), which InvokeAI's environment is m
 
 <Steps>
 1. Open a terminal in your InvokeAI install directory.
-2. Install Triton for Windows, matching the Triton version of InvokeAI's PyTorch (Triton 3.7 for PyTorch 2.13):
-
-   ```powershell
-   uv pip install --python .venv\Scripts\python.exe "triton-windows>=3.7,<3.8"
-   ```
-
-3. Install a SageAttention 2.2 wheel from the [SageAttention for Windows releases](https://github.com/woct0rdho/SageAttention/releases)
+2. Install a SageAttention 2.2 wheel from the [SageAttention for Windows releases](https://github.com/woct0rdho/SageAttention/releases)
    that matches InvokeAI's PyTorch (CUDA 13, PyTorch 2.10 or newer), without letting it touch PyTorch:
 
    ```powershell
    uv pip install --python .venv\Scripts\python.exe --no-deps "https://github.com/woct0rdho/SageAttention/releases/download/v2.2.0-windows.post6/sageattention-2.2.0%2Bcu130torch2.10.0andhigher.post6-cp310-abi3-win_amd64.whl"
    ```
 </Steps>
 
+A manual install without the `cuda` extra also needs Triton for Windows, matching the Triton version of InvokeAI's
+PyTorch (Triton 3.7 for PyTorch 2.13):
+
+```powershell
+uv pip install --python .venv\Scripts\python.exe "triton-windows>=3.7,<3.8"
+```
+
 ### Linux
 
 SageAttention 2 has no prebuilt wheels for Linux. Build it from source into InvokeAI's environment
@@ -86,10 +89,11 @@ with the CUDA toolkit that matches InvokeAI's PyTorch (CUDA 13) installed. Invok
 Linux.
 
 :::caution[Keep it matched to InvokeAI's PyTorch]
-SageAttention is built against PyTorch, and Triton must match PyTorch's version. When an update moves InvokeAI to a new
-PyTorch, install the matching `triton-windows` again on Windows, and on Linux rebuild SageAttention. A wheel for a
-different CUDA major version, or a repair that re-creates the environment, needs a matching SageAttention too. Until
-then InvokeAI logs why it cannot use it and generates with PyTorch's attention.
+SageAttention is built against PyTorch, and Triton must match PyTorch's version. InvokeAI's NVIDIA install on Windows
+x64 and Linux updates Triton together with PyTorch. When an update moves InvokeAI to a new PyTorch, rebuild
+SageAttention on Linux; on Windows, a manual install without the `cuda` extra needs the matching `triton-windows` again.
+A wheel for a different CUDA major version, or a repair that re-creates the environment, needs a matching SageAttention
+too. Until then InvokeAI logs why it cannot use it and generates with PyTorch's attention.
 :::
 
 ## Enabling

docs/src/content/docs/start-here/manual.mdx

@@ -95,10 +95,12 @@ The following commands vary depending on the version of Invoke being installed a
         View Releases
       </LinkButton>
 
-  6. Determine the package specifier to use when installing. This is a performance optimization.
+  6. Determine the package specifier to use when installing: `invokeai`, plus any of these extras in brackets, separated by commas.
 
-      - If you have an Nvidia 16xx or 20xx series GPU, use `invokeai[xformers]`.
-      - If you have an Nvidia 30xx series GPU or newer, or do not have an Nvidia GPU, use `invokeai`.
+      - `cuda`, if you use `--torch-backend=cu130` in the next step (Nvidia GPU on Windows x64 or Linux x86_64). It installs the PyTorch build Invoke is tested with and, on Windows, Triton. Add it only for Invoke 7 or newer, and never with another torch backend: it pins PyTorch's CUDA 13 build, which no other backend provides.
+      - `xformers`, if you have an Nvidia 16xx or 20xx series GPU. This is a performance optimization.
+
+      For example `invokeai[cuda]` for a 30xx series GPU or newer, `invokeai[cuda,xformers]` for a 16xx or 20xx series GPU, or `invokeai` without an Nvidia GPU.
 
   7. Determine the torch backend to use for installation, if any. This is necessary to get the right version of torch installed. This is achieved by using [UV's built in torch support.](https://docs.astral.sh/uv/guides/integration/pytorch/#automatic-backend-selection)
 
@@ -199,7 +201,7 @@ The following commands vary depending on the version of Invoke being installed a
         </TabItem>
         <TabItem label="With torch backend">
           ```sh
-          uv pip install <PACKAGE_SPECIFIER>==<VERSION> --python 3.12 --python-preference only-managed --torch-backend=<VERSION> --force-reinstall
+          uv pip install "<PACKAGE_SPECIFIER>==<VERSION>" --python 3.12 --python-preference only-managed --torch-backend=<VERSION> --force-reinstall
           ```
         </TabItem>
         <TabItem label="Windows on ARM64">

docs/src/content/docs/start-here/system-requirements.mdx

@@ -16,7 +16,7 @@ Hardware requirements vary significantly depending on model and image output siz
 The requirements below are rough guidelines for best performance. GPUs with less VRAM typically still work, if a bit slower. Follow the [Low VRAM Guide] to optimize performance.
 
 - All Apple Silicon (M1, M2, etc) Macs work, but 16GB+ memory is recommended.
-- Nvidia GPUs need compute capability 7.5 or newer (GTX 16xx, RTX 20xx and everything after) and a driver from the R580 series or newer. Maxwell, Pascal and Volta cards (GTX 9xx/10xx, Titan V, Tesla P40/P100/V100) are not supported by Invoke's CUDA build: stay on the previous Invoke release, or do a [manual install](../manual) with `--torch-backend=cu126`, whose PyTorch build still includes these GPUs (not tested by the Invoke team). With a driver that is too old, Invoke starts on the CPU and logs an error saying so; on an unsupported GPU it logs an error at startup and generation fails.
+- Nvidia GPUs need compute capability 7.5 or newer (GTX 16xx, RTX 20xx and everything after) and a driver from the R580 series or newer. Maxwell, Pascal and Volta cards (GTX 9xx/10xx, Titan V, Tesla P40/P100/V100) are not supported by Invoke's CUDA build: stay on the previous Invoke release, or do a [manual install](../manual) with `--torch-backend=cu126` and without the `cuda` extra, whose PyTorch build still includes these GPUs (not tested by the Invoke team). With a driver that is too old, Invoke starts on the CPU and logs an error saying so; on an unsupported GPU it logs an error at startup and generation fails.
 - AMD GPUs are supported on Windows and Linux `x86_64` through ROCm 10 (see [AMD](#amd) below for the GPUs and drivers). On Linux, Vega-based cards (gfx900/gfx906) are no longer supported. The VRAM requirements are the same as Nvidia GPUs.
 - Intel Arc GPUs (Alchemist, Battlemage and newer) are supported on Windows and Linux `x86_64`. The VRAM requirements are the same as Nvidia GPUs.
 - Linux ARM64 (`aarch64`) devices — e.g. Raspberry Pi 5, other SBCs, ARM servers — are supported in CPU-only mode. Local generation is slow without a GPU, but API-backed models (e.g. GPT Image, Gemini) work well.

docs/src/content/docs/troubleshooting/faq.mdx

@@ -48,7 +48,7 @@ Once v7 has run on an install, it has updated the database, and older versions c
 
 ## Triton error on startup
 
-This can be safely ignored. Invoke only uses Triton for [SageAttention](/configuration/optimization/sage-attention/), which is off unless you enable it. If you are on Linux and wish to dismiss the error, you can install Triton.
+Invoke only uses Triton for [SageAttention](/configuration/optimization/sage-attention/), which is off unless you enable it. Installs without Triton can ignore the error: CPU, macOS, AMD on Windows, Windows on ARM64, and a manual Windows install without the `cuda` extra (`--torch-backend=cu126` installs included). Other NVIDIA installs include Triton (on Windows the `triton-windows` package), so there the error means Triton is broken or does not match PyTorch; repair the install from the launcher, or rerun the manual install command.
 
 ## No ffmpeg exe could be found (Windows on ARM64)
 

pyproject.toml

@@ -181,6 +181,9 @@ dependencies = [
 "cuda" = [
   "torch==2.13.0+cu130; (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine != 'ARM64')",
   "torchvision==0.28.0+cu130; (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine != 'ARM64')",
+  # The Linux torch wheel requires triton; the Windows wheel requires none. triton-windows is the Windows build
+  # (no win_arm64 wheel); its minor version must match the Triton that torch 2.13 is built against.
+  "triton-windows>=3.7,<3.8; sys_platform == 'win32' and platform_machine != 'ARM64'",
   # macOS / linux_aarch64 fallback, see note under "cpu"
   "torch==2.7.1; sys_platform == 'darwin' or (sys_platform == 'linux' and platform_machine == 'aarch64')",
   "torchvision==0.22.1; sys_platform == 'darwin' or (sys_platform == 'linux' and platform_machine == 'aarch64')",