Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,7 @@ Current Status: In-progress - Structure is in-place and planned docs are current
- Community Workflows *(planned)* — Browsing community workflows via OpenArt

### Settings
- Overview *(planned)* — Navigating the settings hub
- General *(planned)* — Theme, language, data directory, and shared folder settings
- Accounts *(planned)* — Lykos account, OAuth login, and API tokens
- Inference Settings *(planned)* — Inference UI behavior and defaults
- Updates *(planned)* — Auto-update channel and frequency settings
- [Settings](settings/settings.md) — All application settings covering General, Accounts, Checkpoint Manager, Package Environment, Model Browser, Workflow Browser, Console, Appearance, System, and Debug Options

### Advanced
- [Overview](advanced/overview.md) — Advanced configuration and technical reference
Expand Down
37 changes: 21 additions & 16 deletions docs/advanced/environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,26 +143,31 @@ Most users should leave these alone unless they are troubleshooting a specific R
| `COMFYUI_ENABLE_MIOPEN` | `1` | Tells ComfyUI to keep the MIOpen-backed path enabled on ROCm builds where it may otherwise be disabled by default. Without this enabled, ComfyUI disables the `cudnn` backend path in its backend calls for RDNA3, RDNA3.5, and RDNA4 AMD GPUs, which in turn disables the MIOpen-backed functions that rely on that path. This variable is needed for MIOpen to function properly in those setups. |
| `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL` | `1` | Enables the experimental ROCm AOTriton path in compatible PyTorch builds. In Stability Matrix's Windows ROCm ComfyUI integration, this is used for TheRock technical-preview PyTorch builds to enable AOTriton-provided built-in Flash Attention and PyTorch SDPA memory-efficient attention paths. |

For some Windows ROCm-based ComfyUI launches, Stability Matrix already applies several of these optimizations automatically in package code, including:
For Windows ROCm-based WebUI package launches, Stability Matrix already applies several of these optimizations automatically at package launch as a general all-round baseline. Variables automatically utilized at package launch include:

`MIOPEN_FIND_MODE=2`

`MIOPEN_SEARCH_CUTOFF=1`

`MIOPEN_FIND_ENFORCE=1`

`TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1` (RDNA3 / RDNA3.5 / RDNA4 only, and additionally excluded on the gfx1152/gfx1153 APU architectures where AOTriton isn't yet supported)

`FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`

`COMFYUI_ENABLE_MIOPEN=1` (RDNA3 / RDNA3.5 / RDNA4 only, no gfx1152/gfx1153 exclusion)

`PYTORCH_ALLOC_CONF=max_split_size_mb:512,garbage_collection_threshold:0.8`
| Variable | Value | Notes |
|---|---|---|
| `MIOPEN_FIND_MODE` | `2` | |
| `MIOPEN_SEARCH_CUTOFF` | `1` | |
| `MIOPEN_FIND_ENFORCE` | `1` | |
| `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL` | `1` | Enables the experimental ROCm AOTriton path. Applied only on RDNA3 / RDNA3.5 / RDNA4 GPUs, and additionally excluded on gfx1152/gfx1153 APU architectures where AOTriton isn't yet supported. |
| `FLASH_ATTENTION_TRITON_AMD_ENABLE` | `TRUE` | Enables the Triton-based Flash Attention implementation for AMD GPUs, providing an efficient attention path when the native ROCm Flash Attention is unavailable and instead provided by a separate FA Python package. |
| `COMFYUI_ENABLE_MIOPEN` | `1` | Keeps the MIOpen-backed path enabled in ComfyUI on RDNA3 / RDNA3.5 / RDNA4 GPUs. |
| `PYTORCH_ALLOC_CONF` | `max_split_size_mb:512,garbage_collection_threshold:0.8` | |

Environment Variables automatically enabled for legacy AMD GPU architectures (Vega/GCN5, RDNA1, RDNA2) where certain backend paths are not supported by the hardware or supported well:
| Variable | Value | Notes |
|---|---|---|
| `TORCH_BACKENDS_CUDA_FLASH_SDP_ENABLED` | `0` | Disables the Flash SDP backend. |
| `TORCH_BACKENDS_CUDA_MEM_EFF_SDP_ENABLED` | `0` | Disables the memory-efficient SDP backend. |
| `TORCH_BACKENDS_CUDA_MATH_SDP_ENABLED` | `1` | Enables the math SDP backend as the fallback attention implementation. |


Linux installs do not currently get the same automatic overrides, so they will need to be enabled by the user.
> [!NOTE]
> Linux installs do not currently get the same automatic overrides, so they will need to be enabled by the user.

If you're using the ComfyUI-Zluda package specifically, it also sets its own environment variables at launch on top of the above: `FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`, `MIOPEN_FIND_MODE=2`, `MIOPEN_LOG_LEVEL=3`, and `ZLUDA_COMGR_LOG_LEVEL=1`. If you're wondering why those already appear to be set for a ZLUDA install, this is why.
> [!NOTE]
> ComfyUI-Zluda is not managed by Stability Matrix's internal ROCm handling. If you're using the ComfyUI-Zluda package specifically, it also sets its own environment variables at launch similar to some of the above: `FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`, `MIOPEN_FIND_MODE=2`, `MIOPEN_LOG_LEVEL=3`, and `ZLUDA_COMGR_LOG_LEVEL=1`. If you're wondering why those already appear to be set for a ZLUDA install, this is why.

Whatever you set in Stability Matrix's own environment-variable editor is applied last, so it always overrides these auto-applied defaults if the same variable name is used.

Expand Down
18 changes: 10 additions & 8 deletions docs/advanced/hardware-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,11 @@ The lists below describe what the code checks for. Because hardware detection wo

## AMD on Windows

AMD support on Windows is the most involved case, because there are three different paths depending on your GPU and package: native ROCm (technical preview), ZLUDA, and DirectML.
AMD support on Windows is the most involved case, because there are three different paths depending on your GPU and package: native ROCm, ZLUDA, and DirectML.

### Native ROCm (TheRock technical preview)
### Native ROCm

Stability Matrix can install AMD's native ROCm PyTorch on Windows using AMD's TheRock multi-architecture wheels. This path is gated to a specific set of GPU architectures. The code recognizes the following `gfx` architectures as supported on Windows:
Stability Matrix can install AMD's native ROCm PyTorch on Windows using AMD's official multi-architecture wheels. This path is gated to a specific set of GPU architectures. The code recognizes the following `gfx` architectures as supported on Windows:

- **RDNA4** — `gfx120x` (e.g. RX 9070, RX 9060 families).
- **RDNA3 / RDNA3.5** — `gfx110x` (RDNA3 desktop and mobile) and `gfx115x` (RDNA3.5 APUs such as the 890M / 8060S / Z2 Extreme families).
Expand All @@ -54,15 +54,17 @@ Architectures in the `gfx110x`, `gfx115x`, and `gfx120x` ranges are treated as "

**What Stability Matrix does automatically:**

- When a supported AMD GPU is present on Windows, ROCm becomes the recommended backend for ROCm-capable packages (currently ComfyUI and Comfy-based flows via SwarmUI).
- Torch is installed from AMD's ROCm multi-arch index (`repo.amd.com/rocm/whl-multi-arch/`) as device-specific wheels (`torch[device-gfxNNNN]`). Vega parts (`gfx900` / `gfx906`) pull from the nightly multi-arch feed instead, since TheRock currently only publishes their device packages there.
- When a supported AMD GPU is present on Windows, ROCm becomes the recommended backend for ROCm-capable packages.
- Torch is installed from AMD's ROCm multi-arch index (`repo.amd.com/rocm/whl-multi-arch/`) as device-specific wheels (`torch[device-gfxNNNN]`). Vega parts (`gfx900` / `gfx906`) pull from the 'TheRock' nightly multi-arch feed instead, since these architecture builds currently are only available there instead of the stable production distribution stream.
- On modern architectures it applies a set of ROCm performance and attention environment variables at launch (MIOpen find-mode tuning, AOTriton experimental flash attention, `COMFYUI_ENABLE_MIOPEN`, and an allocator tuning string). AOTriton is excluded on the `gfx1152` / `gfx1153` APU architectures, which it does not yet support. Legacy architectures instead force a math SDP fallback. The full variable list and exactly which ones are auto-applied are documented in [Environment Variables](environment-variables.md#amd-and-rocm-variables).
- ComfyUI offers optional extra commands for supported AMD GPUs, including **Install Triton and SageAttention (ROCm)**, **Install Flash Attention (ROCm)** (legacy architectures), an **Install ROCm Development SDK** step, and an **Install bitsandbytes (ROCm)** step for Python 3.12 environments.
- ComfyUI offers optional extra commands for supported AMD GPUs, including **Install Triton and SageAttention (ROCm)** (Sage Attention 1.x), **Install Flash Attention (ROCm)** (legacy architectures), an **Install ROCm Development SDK** step, and an **Install bitsandbytes (ROCm)** step for Python 3.12 environments.
- **Packages:** ComfyUI, Stable Diffusion WebUI Reforge, InvokeAI, SwarmUI, and Wan2GP are supported by this install path.
> [!NOTE] While not managed by Stability Matrix for ROCm installs, SD.Next has a Windows-native ROCm install when the "ROCm" Pytorch index is selected in Advanced Installation Options during initial package install and `--use-rocm` is set in launch options. This install path is internally handled by SD.Next itself and currently only supports RDNA2 dedicated GPUs, RDNA3, RDNA3.5, and RDNA4 GPUs.

**Caveats:**

- Windows AMD ROCm is explicitly experimental. Stability Matrix prints a notice asking you to report issues to Stability Matrix first, since the setup may not be officially supported by the upstream package developers.
- Only the architectures listed above are eligible. If your AMD GPU is not on the list, the recommended default becomes ZLUDA or DirectML instead.
- Windows AMD ROCm implementation for Stability Matrix is explicitly in an experimental state. While these package installations are generally in a working state, untested or edge-case issues and incompatibilities may appear. Stability Matrix prints a notice asking you to report issues to Stability Matrix first, since the setup may not be officially supported by the upstream package developers.
- Only the architectures listed above are eligible. If your AMD GPU is not on the list, the recommended default becomes ZLUDA or DirectML instead. For a more detailed list of compatible AMD GPU architectures, please refer to the ROCm/TheRock [GPU Support](https://github.com/ROCm/TheRock/blob/main/SUPPORTED_GPUS.md#rocm-on-windows) table.

### ZLUDA

Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Stability Matrix is cross-platform, but the exact release formats and hardware t
| Operating System | Version / Target | Architecture | Notes |
|---|---|---|---|
| Windows | Windows 10 and Windows 11 | x64 | Official release builds are published for `win-x64`. This is the broadest-supported desktop target for Stability Matrix and most package workflows. |
| Linux | Modern x86-64 desktop distributions | x64 | Official Linux releases are published for `linux-x64`, primarily as an AppImage, with an AUR package also available for Arch-based systems. Depending on the distribution, AppImage/runtime support packages such as `libfuse2`, `libappimage`, or `libxcrypt-compat` may be needed if they are not already provided by the system. |
| Linux | Modern x86-64 desktop distributions | x64 | Official Linux releases are published for `linux-x64`, primarily as an AppImage, with an AUR package also available for Arch-based systems. Depending on the distribution, runtime support packages such as `fuse3` or `libxcrypt-compat` may be needed if they are not already provided by the system. |
| macOS | Apple Silicon Macs, with macOS 12.3 or later recommended for AI workflows | arm64 | Official macOS releases are published for Apple Silicon (`osx-arm64`) as a `.dmg`. The app's AI workflows rely on the MPS backend on Apple Silicon. |

In other words, the practical supported release targets are Windows x64, Linux x64, and Apple Silicon macOS. Some project files include additional runtime identifiers, but the documented source-build support and the release pipeline currently focus on `win-x64`, `linux-x64`, and `osx-arm64`. For work from a local checkout instead of a packaged release, a planned Building from Source and Contributing page will serve as the documentation entry point and link to the repository's contributor guide.
Expand Down
2 changes: 1 addition & 1 deletion docs/package-manager/installing-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ The **PyTorch backend** determines which GPU acceleration library your package u
| Backend | Platform | GPU | Notes |
|---------|----------|-----|-------|
| **CUDA** | Windows, Linux | NVIDIA (GTX 900-series and newer) | Best performance and broadest compatibility. CUDA toolkit is bundled with PyTorch; no separate driver installation beyond standard NVIDIA drivers. Turing (RTX 2000-series) or newer recommended. |
| **ROCm** | Windows, Linux | AMD (select GPUs per platform) | Native AMD GPU acceleration. On Linux, requires system-level ROCm installation. On Windows, uses AMD's TheRock technical preview builds. Per-chip compatibility details are planned for a future Hardware Support page. |
| **ROCm** | Windows, Linux | AMD (select GPUs per platform) | Native AMD GPU acceleration. On Linux, requires system-level ROCm installation. Package support is more limited on Windows. Per-chip compatibility details are planned for a future Hardware Support page. |
| **DirectML** | Windows | AMD, Intel, some NVIDIA | Microsoft's DirectML API. Broad compatibility but slower performance than CUDA or ROCm. Development is largely stagnant; consider native ROCm, or ZLUDA if need be, as an alternative for AMD GPUs. |
| **ZLUDA** | Windows | AMD (via CUDA translation layer) | Experimental CUDA-to-AMD translation layer. Used by the ComfyUI-Zluda, SD.Next, and AMDGPU Forge packages. Generally faster than DirectML for supported operations. |
| **IPEX** | Windows, Linux | Intel Arc (discrete and integrated) | Intel Extension for PyTorch. Requires Intel Arc GPU (A-series, B-series) or modern Intel Core Ultra with integrated Arc graphics. |
Expand Down
Loading
Loading