|
| 1 | +# Installing Packages |
| 2 | + |
| 3 | +This page walks through installing an WebUI package in Stability Matrix using the **Add Package** screen. |
| 4 | + |
| 5 | +[`Section Overview`](overview.md) | [`Home`](../README.md) |
| 6 | + |
| 7 | +## Table of Contents |
| 8 | + |
| 9 | +- [The Add Package Screen](#the-add-package-screen) |
| 10 | +- [Package Detail View](#package-detail-view) |
| 11 | +- [Selecting a Version](#selecting-a-version) |
| 12 | +- [Selecting a Hardware Backend](#selecting-a-hardware-backend) |
| 13 | +- [Installation Progress](#installation-progress) |
| 14 | +- [One-Click Install](#one-click-install) |
| 15 | + |
| 16 | +--- |
| 17 | + |
| 18 | +## The Add Package Screen |
| 19 | + |
| 20 | +The **Add Package** screen is where you discover and install new WebUI packages. To access it, navigate to **Packages** from the main navigation sidebar, then click the **Add Package** button across the bottom of the packages view. |
| 21 | + |
| 22 | +Packages are displayed as a scrollable list of cards organized into three tabs above the package search bar: |
| 23 | + |
| 24 | +- **Inference**: Image/video generation tools such as ComfyUI, Stable Diffusion WebUI, and Fooocus. |
| 25 | +- **Training**: Model fine-tuning and training tools such as Kohya's GUI and OneTrainer. |
| 26 | +- **Legacy**: Older packages that are maintained for existing users but not recommended for new installations. May be stale and no longer receiving updates. |
| 27 | + |
| 28 | +Each package card shows the package name, author, a short description, and a row of **hardware compatibility badges** indicating which PyTorch backends the package supports from the following types CUDA (NVIDIA), ROCm (AMD-native), DirectML, macOS (MPS), ZLUDA (AMD), IPEX (Intel), or CPU. Note that the absence of a particular hardware badge does not necessarily mean the package is incompatible, some packages may still be usable with manual configuration or community-provided workarounds. Within each tab, beginner-friendly packages appear first, followed by advanced tools in alphabetical order. |
| 29 | + |
| 30 | +Use the tabs to switch between package types, or type in the search bar to filter the list by name in real time. Incompatible packages are hidden by default: enable *Show All Packages* to see packages that do not officially support your current hardware (e.g., CUDA-only packages on an AMD system). |
| 31 | + |
| 32 | +## Package Detail View |
| 33 | + |
| 34 | +Clicking a package card opens the **package detail screen**, where you configure your installation before proceeding. The left side shows a preview image of the package; the right side contains all configuration options. |
| 35 | + |
| 36 | +The following fields are shown at the top of the screen: |
| 37 | + |
| 38 | +- **License and GitHub links**: Buttons to view the package's license and open its source repository. |
| 39 | +- **Version selector**: Choose between **Releases** (tagged GitHub releases) and **Branches** (development branches with optional commit selection). See [Selecting a Version](#selecting-a-version). |
| 40 | +- **Display Name**: An editable field that sets both the display name and folder name for the installation. Defaults to the package's canonical name. Changing this allows installing multiple copies of the same package under different names. The full install path is shown below the field. |
| 41 | + |
| 42 | +A *Duplicate Warning* banner appears if an installation with the same name already exists. Change the **Display Name** field to proceed. |
| 43 | + |
| 44 | +### Advanced Options |
| 45 | + |
| 46 | +The **Advanced Options** section is a collapsible panel containing settings that most users can leave at their defaults: |
| 47 | + |
| 48 | +- **Model Sharing**: Controls how model directories are linked to the shared `Models/` library. Options include **Symlink** (recommended for most users), **Configuration** (uses the package's own config files to point to shared paths), and **None** (isolated model folders). |
| 49 | +- **PyTorch Index**: Choose the PyTorch compute backend for your GPU. See [Selecting a Hardware Backend](#selecting-a-hardware-backend). |
| 50 | +- **Output Sharing**: Enabled by default. When enabled, generated outputs are saved to the shared `Images/` directory rather than inside the package folder. |
| 51 | +- **Python Version**: Select the Python version for the package's virtual environment from the versions available via Stability Matrix's internal `uv` utility. A green checkmark indicates versions already downloaded and cached locally. Typically it is recommended to leave set to what the package is configured in SM as default for compatibility/upstream recommendation and, recommended only to change if specifically needed before installing. |
| 52 | + |
| 53 | +### Python Dependencies Override |
| 54 | + |
| 55 | +The **Pip Override** section is a separate collapsible panel that lets you override specific Python package dependencies during installation and updates. It presents a data grid where each row defines an override with three fields: |
| 56 | + |
| 57 | +- **Action**: **Update** to change a dependency's version or constraint, or **Remove** to exclude it entirely. |
| 58 | +- **Name**: the pip package name of the dependency to override. |
| 59 | +- **Constraint** and **Version**: the version specifier (e.g., `>=`, `==`, `!=`) and target version to pin. |
| 60 | + |
| 61 | +This is useful when you need to force a specific version of a dependency to resolve a compatibility issue, or to remove a problematic package from the install. For example, you might pin `numpy==1.26.4` or remove an optional dependency that causes conflicts. |
| 62 | + |
| 63 | +### Installing |
| 64 | + |
| 65 | +The **Install** button sits at the bottom of the screen, below all configuration options. It is disabled until a valid configuration is selected (no duplicate name, all required fields populated). Click it to begin the installation pipeline described in [Installation Progress](#installation-progress). |
| 66 | + |
| 67 | +## Selecting a Version |
| 68 | + |
| 69 | +Stability Matrix offers two version selection modes, controlled by the **Branches/Release** tab toggle on the package detail screen: |
| 70 | + |
| 71 | +### Release Mode (Recommended) |
| 72 | + |
| 73 | +Select from the package's published GitHub releases. This is the default and recommended mode for most users: |
| 74 | + |
| 75 | +- **Latest release** (default): installs whichever release tag is newest at the time of installation, excluding pre-releases. |
| 76 | +- **Specific release**: choose any tagged release from the dropdown, including pre-release versions if available. |
| 77 | + |
| 78 | +Releases represent tested, versioned snapshots of the package and are recommended for users who prioritize stability. |
| 79 | + |
| 80 | +### Branch Mode |
| 81 | + |
| 82 | +For packages that do not publish formal releases, or for users who need the latest development changes, switch to branch mode: |
| 83 | + |
| 84 | +- **Branch select**: choose a branch from the package's Git repository (e.g., `main`, `master`, `dev`). |
| 85 | +- **Commit select** (Advanced Options): pick a specific commit on the selected branch. Dropdown will list the latest 10 commit hashes, with the newest (HEAD) being first listed. |
| 86 | +- **Custom commit** (Advanced Options): enter the full commit SHA manually. |
| 87 | + |
| 88 | +Branch mode is useful for testing bleeding-edge features that have not yet been packaged in a release. Use it with the understanding that development branches may be unstable or contain breaking changes. |
| 89 | + |
| 90 | +> **Tip:** Some packages disable release mode because they do not publish GitHub releases, or the Releases install path is currently incompatible/not configured with StabilityMatrix. In those cases, only branch mode is available. |
| 91 | +
|
| 92 | +## Selecting a Hardware Backend |
| 93 | + |
| 94 | +The **PyTorch backend** determines which GPU acceleration library your package uses for computation. Stability Matrix detects your hardware and pre-selects the recommended backend, but you can override it from the dropdown on the package detail screen. |
| 95 | + |
| 96 | +| Backend | Platform | GPU | Notes | |
| 97 | +|---------|----------|-----|-------| |
| 98 | +| **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. | |
| 99 | +| **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. See [Hardware Support](../advanced/hardware-support.md#amd-rocm) for per-chip compatibility. | |
| 100 | +| **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. | |
| 101 | +| **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. | |
| 102 | +| **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. | |
| 103 | +| **MPS** | macOS | Apple Silicon (M1 and newer) | Apple's Metal Performance Shaders backend. Included with PyTorch on macOS; no additional setup required. | |
| 104 | +| **CPU** | All | None | Runs entirely on the CPU. Significantly slower than any GPU backend. Suitable only for testing or systems with no compatible GPU. | |
| 105 | + |
| 106 | +The pre-selected backend is determined by Default GPU selected at First-Launch or in Default GPU setting, along with internal recommended Torch checks Stability Matrix determines based on detected hardware. If a package does not support your detected GPU, the recommended default will fall back to CPU. |
| 107 | + |
| 108 | +> **Note:** The PyTorch backend is selected at install time, but can be changed afterward via the **Python Packages** dialog — accessible from the package's three-dot menu on the Packages screen. See [Python Environment Management](../advanced/python-environment.md#viewing-installed-python-packages). |
| 109 | +
|
| 110 | +For in-depth platform-specific guidance, including driver requirements and known caveats, see [Hardware Support](../advanced/hardware-support.md). |
| 111 | + |
| 112 | +## Installation Progress |
| 113 | + |
| 114 | +Once you click **Install**, Stability Matrix executes the installation as a sequence of discrete steps. A progress dialog appears, showing the current step and overall progress. The installation pipeline runs the following steps in order: |
| 115 | + |
| 116 | +| Step | What Happens | |
| 117 | +|------|--------------| |
| 118 | +| **1. Mark as Installing** | The package name is added to the in-progress installs list so other operations can avoid conflicts with the installation directory. | |
| 119 | +| **2. Setup Prerequisites** | Stability Matrix ensures that required tools (`git`, `uv`, and the target Python version) are available. Missing prerequisites are downloaded and unpacked automatically into the Stability Matrix data directory. No system-wide Python or Git installation is required. | |
| 120 | +| **3. Download Package** | The package's Git repository is cloned from GitHub to the `Packages/<InstallName>` directory inside your library. The specific version (release tag, branch, or commit) selected on the detail screen is checked out. | |
| 121 | +| **4. Unpack Site Customize** | A `sitecustomize.py` bootstrap script is placed in the virtual environment to ensure the package uses the correct Python path configuration at runtime. | |
| 122 | +| **5. Install Package** | A Python virtual environment (`venv`) is created at `Packages/<InstallName>/venv/` using `uv`. Stability Matrix then installs the package's Python dependencies, including the selected PyTorch backend variant, by running `uv pip install` with the package's requirements file. This step typically takes the longest, as large PyTorch wheels are downloaded. | |
| 123 | +| **6. Setup Model Folders** | Symbolic links or configuration files are created to connect the package's model directories (e.g., `models/stable-diffusion`, `models/VAE`) to the shared `Models/` library. | |
| 124 | +| **7. Setup Output Sharing** | If output sharing is enabled, the package's output directory is linked to the shared `Images/` folder. | |
| 125 | +| **8. Register Package** | The installed package is saved to the settings file with its full metadata: version, backend, Python version, and configuration. It now appears in your **Installed Packages** list and is ready to launch. | |
| 126 | + |
| 127 | +The progress dialog shows a real-time log of each step. If any step fails, the dialog reports the error, and you can inspect the full console output for troubleshooting. |
| 128 | + |
| 129 | +### Typical Install Times |
| 130 | + |
| 131 | +| Scenario | Approximate Time | |
| 132 | +|----------|------------------| |
| 133 | +| Fast connection, cached PyTorch wheels | 2–5 minutes | |
| 134 | +| First install (no cached wheels) | 5–15 minutes | |
| 135 | +| Slow connection or CPU-only install | 10–25 minutes | |
| 136 | + |
| 137 | +> **Note:** PyTorch wheels are large and the multiple needed WHL files needed can accumulate to several GB's or more in total download size depending on backend used. The first installation on a fresh system downloads these wheels. Subsequent installs reuse cached wheels, making them significantly faster. |
| 138 | +
|
| 139 | +## One-Click Install |
| 140 | + |
| 141 | +For new users, Stability Matrix offers a streamlined **one-click install** experience that appears on first launch. This guided flow installs a recommended package with sensible defaults, requiring no configuration decisions. |
| 142 | + |
| 143 | +### How It Works |
| 144 | + |
| 145 | +1. **Welcome dialog**: on the first launch after a fresh install, Stability Matrix presents a welcome screen with a brief explanation and a large **Install** button. The first compatible package that offers one-click installation is pre-selected; you can choose a different package from the dropdown if desired. |
| 146 | + |
| 147 | +2. **Automatic configuration**: the one-click flow selects sensible defaults automatically: |
| 148 | + - The **latest release version** (or latest commit, for packages without releases). |
| 149 | + - The **recommended PyTorch backend** detected from your hardware. |
| 150 | + - The **recommended shared folder method** (symlinks for most packages). |
| 151 | + - The **package's recommended default Python version** |
| 152 | + |
| 153 | +3. **Installation**: clicking Install runs the same step pipeline described in [Installation Progress](#installation-progress). A progress bar shows the current status, and status text updates as each step completes. |
| 154 | + |
| 155 | +4. **Post-install**: after successful installation, a brief countdown appears and the dialog closes, returning you to the Packages screen with the newly installed package ready to launch. |
| 156 | + |
| 157 | +### Skipping One-Click Install |
| 158 | + |
| 159 | +If you prefer to explore the full Add Package screen or already know which package you want, click the **Skip first-time setup** link at the bottom of the one-click dialog. This closes the dialog and leaves you at the main Package Manager interface. |
| 160 | + |
| 161 | +### Re-accessing the One-Click Flow |
| 162 | + |
| 163 | +The one-click install dialog is a first-launch experience only. Once dismissed or completed, it does not reappear. All subsequent package installations are done through the standard **Add Package** → package detail workflow described in the sections above. |
| 164 | + |
| 165 | +## Next Steps |
| 166 | + |
| 167 | +Once a package is installed, you can launch it, monitor its console output, configure launch arguments, run multiple packages simultaneously, update to newer versions, or remove it entirely. See [Managing Packages](managing-packages.md) for details on all of these workflows. |
0 commit comments