Stability Matrix Docs

Appearance

v2.16.3 Technical Notes ​

Extended technical notes for the v2.16.3 release — the deeper "how and why" behind each change. For the user-facing summary, see the CHANGELOG.

Home

Table of Contents ​

CivitAI Workflow Browsing ​

This release's headline grew out of a subtraction: OpenArt discontinued its ComfyUI workflow community — the site no longer has workflow pages, nothing new had been uploaded since March, and the unmoderated "latest" feed had filled with spam. Rather than keep filtering a dead catalog, the browser's source was replaced with a live one: CivitAI workflows.

Browsing and importing. The Model Browser gains the CivitAI Workflows model type (workflows also surface in All-type searches). Importing a workflow downloads the release archive, extracts the workflow JSONs into the Workflows library, and embeds library metadata in each file. Model-only surfaces — install locations, bulk download, the cm-info sidecars — are bypassed for workflow models so sidecar files can't appear as phantom entries in the library.

Images with embedded workflows. Some CivitAI workflow packs ship zips of PNGs rather than JSON files (for example WAN 2.2 Kijai Wrapper). ComfyUI embeds the full workflow graph in a workflow tEXt chunk when saving images — that's what makes drag-into-ComfyUI work. The import step extracts that chunk from .png archive entries and bare .png files, imports it as a regular workflow JSON (so the ComfyUI folder link below keeps working), and keeps the image itself as the workflow's preview. Images without an embedded workflow are skipped, and the no-workflows error message covers both shapes. The chunk format was verified against real ComfyUI output files (uncompressed tEXt, keyword workflow).

Custom node install assist. The removed OpenArt browser offered node installs at import time; without a replacement, 2.16.3 would have lost that capability. Imported workflows now carry the node packs they need in embedded cnr_id/aux_id node properties; after import, Stability Matrix reads those out, matches them against the extension index (registry ID first, repo/title as fallback), shows which are already installed, and offers one-click installs for the rest. The dialog only auto-opens when something is actionable. When an import finds nothing importable, the message explains WebUI-parameter images too.

ComfyUI linking. The shared Workflows library is now linked into every installed ComfyUI-based package as user/default/workflows/Stability Matrix, so imported workflows appear natively in ComfyUI's own workflow browser (ComfyUI-Zluda inherits this; the link is skipped when shared folders are disabled).

Library page and previews. The Workflows page drops its tab bar — it is now the installed workflow library directly, since browsing moved to the Model Browser; cards for CivitAI imports link back to their source page, and legacy OpenArt imports keep working minus the now-dead site link. Because workflow screenshots are often full-graph captures (thousands of pixels, multiple MB), imported PNG previews and metadata-editor image picks are downscaled to 1024px on the longest side before being written as the preview sidecar, and the CivitAI thumbnail URL stored in imported metadata gets its width transform capped at 700 — so the library page no longer decodes heavyweight images per card.

In-App Documentation ​

Shipped in v2.16.2 but left out of that release's notes by mistake, so it is recorded here. The full Stability Matrix guides are now readable without leaving the app: press F1 from anywhere, or open it from Settings → About → Documentation. Contextual ? buttons on the Package Manager, install details, the running package console, Inference, and the Environment Variables and App Folders settings open the page for what you're looking at. Pages are read live from docs.lykos.ai so new and updated writing shows up without an app update, with an offline copy bundled inside the app; the zoom level is remembered.

CivArchive Browser After the Site Redesign ​

CivArchive redesigned its site and API without notice, breaking the in-app browser in several quiet ways:

  • Truncated results. The redesign pinned the app's search route to the past quarter, and a renamed result-count field capped infinite scroll at a single page — the browser showed far fewer results than the website.
  • Whole-model search results. The new search returns whole-model entries whose detail pages load through a redirect the app didn't follow, so clicking them errored instead of opening the model.
  • Renamed API fields. File results opened in the web browser instead of the in-app details page, and the details page's version dropdown did nothing — both casualties of one renamed field in the redesigned API.
  • Preview backfill and polish. Cards without a preview (whole-model and file results) now backfill an image from the model's gallery in the background instead of staying gray placeholders; trigger-word entries that are whole prompt lines now wrap instead of being cut off; and article results, which have no in-app page, open in the web browser instead of erroring.

Model Update Checks ​

Phantom "Update Available" badges (#1716). The update check didn't count embeddings, VAEs, upscalers, or ControlNets as evidence of being up to date, so those file types were flagged forever. They now count, and wrong badges clear on the next check.

Multi-architecture models. Listings that combine several architectures (e.g. Illustrious | Pony | NoobAI) previously counted a release for a different architecture as an update. Update checks now compare within your installed version's base model, so the update and early-access badges reflect the actual successor on your track.

Early access detection. CivitAI now marks early-access versions via a deadline field while reporting them as public, which broke both the early-access update badge and the Model Browser's Hide Early Access Models filter. Both read the new field.

Model Index and Case-Conflicting Folders ​

Linux startup crash (#1715, also #1149/#1357). On case-sensitive filesystems, a models folder containing names differing only in letter case (e.g. unet and Unet) crashed the app on startup while building the model index. Index paths are now canonicalized case-insensitively so differently-cased folders are recognized as one, their models show up in the Checkpoint Manager instead of being silently skipped, and a model index error can no longer take down the app. Covered by a dedicated canonicalization test suite.

Model Browser Fixes ​

A trio of browser bugs fixed together:

  • Cover images with # in the File Name Pattern (#1703) — a # in the pattern broke the file-URI construction used to display model cover/preview images.
  • Scrambled search order (#1705) — refreshing with the Search button showed results in a scrambled order.
  • Wrong-file downloads (#1710) — when several files on one model version share identical metadata, a download could fetch a different file than the one selected and then fail hash verification. Downloads now pin the exact file.

Extension Install and Detection Fixes ​

Extensions the app couldn't see (#1717). Inference and Image Lab asked you to install ComfyUI extensions you already had (most often ComfyUI-GGUF), with the same prompt returning after every install. Two causes: extensions installed from the ComfyUI registry — which ComfyUI-Manager unpacks rather than cloning — weren't being seen at all, and git clones were only recognized when their remote URL matched ours character for character, so a .git suffix or an SSH remote was enough to miss. Detection now covers registry-installed extensions and matches git remotes structurally.

Legacy source builds. Custom node install scripts that shell out to plain pip (e.g. installing the legacy cupy-wheel sdist, which imports pkg_resources) failed on builds with modern setuptools. Those pip runs now get the same setuptools<82 build constraint that package installs already applied via uv, through PIP_CONSTRAINT pointed at the venv's build constraints — closing the gap the uv-only constraint didn't cover.

Layer Diffuse (#1707). Inference's Layer Diffuse addon failed at the sampler with 'NoneType' object is not subscriptable on current ComfyUI. The fix lives in the Inference Core Nodes extension; Inference now offers the extension update when your installed copy predates it.

Python, uv, and Package Environments ​

uv 0.12.5 adds newer Python builds to the picker — including the 3.10 security releases requested in #1709.

uv on the launch PATH (#1713). uv-dependent packages (e.g. Forge Neo) failed to launch on Linux and macOS with Error: 2 uv not found: the bundled uv was only on PATH on Windows. The bundled uv directory is now prepended to PATH in the non-Windows launch path too.

Python fallback version matching. The uv Python fallback used substring matching, so a request for 3.12 could match 3.13.12 or 3.121. The version is now parsed structurally from the install directory name (tolerating prerelease and free-threaded suffixes) and Major/Minor must match — and the actual parsed version is reported instead of the requested one.

pyvenv.cfg rewriting. The ConfigParser-based writer was replaced with a purpose-built ordered key=value parser/writer. Setting a key rewrites every duplicate (fixing stale home/base-* entries when pyvenv.cfg contains duplicate keys), UTF-16/NUL-encoded files now fail loudly instead of being silently mangled, and duplicate-key resolution when multiple Python distributions are installed was fixed so one package's environment can't be rewritten onto another's interpreter.

Package environment breakage. Installing a package that needs a newer Python (e.g. 3.13) next to an existing 3.12 package broke the older package's environment with error no: 2, and hand-repairs didn't hold because the config was rewritten on every launch. With the pyvenv.cfg fixes above, each package's environment stays pinned to its own interpreter.

Trainer and Platform Fixes ​

AI-Toolkit PyTorch 2.13.0. New installs get PyTorch 2.13.0 on CUDA 13.0 with Python 3.12, matching current upstream requirements (#1714); launch shows a console warning if your NVIDIA driver is older than the 580 series CUDA 13.0 needs.

OneTrainer on Windows ROCm (#1708). Training crashed at the start with bitsandbytes 8-bit optimizers because the bundled wheel drifted from the 0.49.1 build OneTrainer itself expects. The helper now pins bitsandbytes 0.49.1, restoring 8-bit optimizers. Thanks to @NeuralFault for the diagnosis and @0xDELUXA for the wheel.

SwarmUI Launch Mode. The dropdown option had no effect — it passed a hyphen where SwarmUI expects --launch_mode. The dropdown also gains a none option to stop SwarmUI opening a browser window on launch.

Clear Finished. The Activity popout's Clear Finished also cleared failed downloads, taking their Retry button with them. Failed items now stay until you retry or dismiss them yourself. Thanks to @NeuralFault.