# Stable Diffusion WebUI — Administrator & Developer Guide

## 1. Architecture Overview

Stable Diffusion WebUI (commonly called "A1111") is a full-featured browser interface for Stable Diffusion image generation. The application is built in Python and combines Gradio 3.41.2 for the interactive UI with FastAPI for a programmatic REST API. It supports text-to-image generation, image-to-image transformation, inpainting, outpainting, upscaling, face restoration, textual inversion training, hypernetwork training, LoRA/LyCORIS networks, and a rich extension ecosystem.

The system follows a monolithic single-process architecture where a single Python process hosts both the Gradio web interface and the FastAPI API server. Image generation requests are serialized through a FIFO queue lock, ensuring only one generation runs at a time on the GPU. The application modifies ("hijacks") the underlying Stable Diffusion model at runtime to inject attention optimizations, custom embeddings, and extra network weights without altering the original model code.

Startup is a multi-stage bootstrap: shell scripts set environment variables, `launch.py` prepares the Python environment and installs dependencies, then `webui.py` initializes the model pipeline, builds the Gradio interface, mounts the API, and starts the server. The entire application state is managed through global singletons in `modules/shared.py`, making the system straightforward to extend but tightly coupled.

### Architecture Diagram

```
webui.sh / webui.bat
  └── webui-user.sh / webui-user.bat  (user env vars: COMMANDLINE_ARGS, etc.)
       └── launch.py
            ├── modules/launch_utils.py   (prepare_environment: git clone deps, pip install)
            └── webui.py
                 ├── modules/initialize.py        (imports, fixes, settings load)
                 ├── modules/initialize_util.py    (setup_middleware, configure_sigint)
                 ├── modules/shared.py             (global state: opts, state, sd_model)
                 ├── modules/sd_models.py           (load checkpoint → GPU)
                 ├── modules/ui.py                  (build Gradio Blocks interface)
                 ├── modules/api/api.py             (mount FastAPI routes under /sdapi/v1/)
                 └── Gradio app.launch()
                      ├── Browser UI (localhost:7860)
                      └── REST API  (/sdapi/v1/*)
```

### Component Inventory

| Component | Path | Role |
|-----------|------|------|
| Launch bootstrap | `launch.py` | Entry point; delegates to `launch_utils.py` then starts `webui.py` |
| Environment prep | `modules/launch_utils.py` | Clones repositories, installs pip packages, validates Python/torch |
| Application core | `webui.py` | Initializes model, UI, API; manages restart loop |
| Initialization | `modules/initialize.py`, `modules/initialize_util.py` | Import fixes, middleware, signal handling |
| Global state | `modules/shared.py` | Singletons: `opts`, `state`, `sd_model`, `device` |
| CLI arguments | `modules/cmd_args.py` | Defines all 129 command-line flags |
| Image processing | `modules/processing.py` | Core generation pipeline for txt2img and img2img |
| Model management | `modules/sd_models.py` | Checkpoint discovery, loading, switching |
| Sampler system | `modules/sd_samplers*.py` | k-diffusion and timestep-based samplers |
| VAE management | `modules/sd_vae.py` | VAE discovery and loading |
| Model hijacking | `modules/sd_hijack.py` | Runtime model modification for optimizations |
| Attention opts | `modules/sd_hijack_optimizations.py` | xformers, SDP, sub-quadratic attention |
| Script system | `modules/scripts.py` | Script base class, discovery, execution |
| Callbacks | `modules/script_callbacks.py` | 30+ extension callback hooks |
| Extensions | `modules/extensions.py` | Extension loading, metadata, dependency management |
| Extra networks | `modules/extra_networks.py` | LoRA, hypernetwork, embedding activation via prompt |
| UI construction | `modules/ui.py` | Full Gradio Blocks interface definition |
| REST API | `modules/api/api.py` | 35+ FastAPI endpoints |
| Safe unpickle | `modules/safe.py` | `RestrictedUnpickler` for model file security |
| Image utilities | `modules/images.py` | Saving, grids, EXIF metadata, filename patterns |
| Prompt parsing | `modules/prompt_parser.py` | Emphasis, scheduling, alternation syntax |
| Options system | `modules/options.py` | Settings definitions with `OptionInfo` |
| Generation queue | `modules/call_queue.py` | FIFO lock serializing GPU work |
| Progress tracking | `modules/progress.py` | Task progress with live preview |
| Cache | `modules/cache.py` | diskcache-based persistent cache |
| Device management | `modules/devices.py` | GPU selection, dtype, garbage collection |
| Paths | `modules/paths.py`, `modules/paths_internal.py` | Directory resolution |
| Upscaling | `modules/upscaler.py` | Base class for ESRGAN, SwinIR, etc. |
| Interrogation | `modules/interrogate.py` | CLIP/BLIP image captioning |
| Low VRAM | `modules/lowvram.py` | Sequential module offloading |
| System info | `modules/sysinfo.py` | Diagnostic information dump |

### Technology Stack

| Technology | Version | Purpose |
|------------|---------|---------|
| Python | 3.10+ | Runtime |
| Gradio | 3.41.2 | Web UI framework |
| FastAPI | (via Gradio) | REST API |
| PyTorch | 2.1.2+ | Deep learning backend |
| transformers | 4.30.2 | Model architectures (CLIP, etc.) |
| xformers | 0.0.23.post1 | Memory-efficient attention (optional) |
| k-diffusion | (pinned commit) | Sampling algorithms |
| safetensors | (latest) | Safe model file format |
| Pillow | 9.5.0+ | Image processing |
| numpy | (latest) | Numerical operations |
| tqdm | (latest) | Progress bars |
| diskcache | 5.6.1 | Persistent caching |
| piexif | 1.1.3 | EXIF metadata |
| httpx | 0.24.1 | HTTP client |
| tomesd | 0.1.3 | Token merging optimization |
| blendmodes | 2022 | Layer blending |
| open-clip-torch | 2.20.0 | CLIP interrogation |
| kornia | 0.7.1 | Computer vision operations |
| spandrel | 0.3.4 | Upscaler model loading |
| lark | 1.1.2+ | Grammar parsing for prompt syntax |

> [!NOTE]
> Gradio embeds its own Uvicorn/FastAPI server. The WebUI mounts additional FastAPI routes onto Gradio's existing ASGI application rather than running a separate server process.

### Data Flow

```
User prompt (text)
  → modules/prompt_parser.py       parse emphasis (a:1.1), scheduling [from:to:step], alternation
  → modules/processing.py          StableDiffusionProcessingTxt2Img / Img2Img
    → modules/sd_hijack.py         apply embeddings, extra networks (LoRA, hypernetworks)
    → modules/sd_samplers*.py      noise scheduling + denoising loop (Euler, DPM++, etc.)
      → UNet forward pass          (hijacked attention: xformers/SDP/sub-quad)
    → VAE decode                   latent → pixel space
  → modules/images.py              save PNG/JPEG with metadata, build grids
  → Gradio gallery / API response
```

---

## 2. System Requirements

### Hardware Requirements

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| GPU VRAM | 4 GB (with `--lowvram`) | 8+ GB |
| System RAM | 8 GB | 16+ GB |
| Disk space | 10 GB (base + 1 model) | 50+ GB (multiple models) |
| CPU | Any x86_64 / ARM64 | Modern multi-core |

### Software Requirements

| Software | Requirement |
|----------|-------------|
| Python | 3.10.6+ (3.10 recommended; 3.11/3.12 supported) |
| Git | Any recent version |
| CUDA Toolkit | 12.1 (for NVIDIA GPUs, bundled via PyTorch wheels) |
| ROCm | 5.6+ (for AMD GPUs on Linux) |

### Supported GPU Platforms

| Platform | Flag / Config | Notes |
|----------|--------------|-------|
| NVIDIA CUDA | Default | Best supported; xformers available |
| AMD ROCm | `--use-cpu` not needed if ROCm torch installed | Linux only; set `TORCH_COMMAND` for ROCm wheels |
| Intel XPU (IPEX) | `--use-ipex` | Intel Arc/Data Center GPUs via Intel Extension for PyTorch |
| Apple MPS | Auto-detected on macOS | Metal Performance Shaders backend |
| Ascend NPU | Auto-detected via `torch_npu` | Huawei Ascend accelerators |
| DirectML | Separate fork required | AMD/Intel on Windows |
| CPU | `--use-cpu all` | Extremely slow; functional for testing |

> [!IMPORTANT]
> The `--skip-torch-cuda-test` flag bypasses the CUDA availability check at startup. This is required for non-CUDA platforms (ROCm, IPEX, MPS, CPU) to prevent the launcher from aborting.

---

## 3. Configuration Reference

### 3.1 CLI Flags

All 129 flags defined in `modules/cmd_args.py`. Flags are parsed at startup and accessible via `modules/shared.cmd_opts`.

#### Launch Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--update-all-extensions` | bool | false | Launch-time: update all extensions before starting |
| `--skip-python-version-check` | bool | false | Skip Python version compatibility check |
| `--skip-torch-cuda-test` | bool | false | Skip CUDA availability test at startup |
| `--reinstall-xformers` | bool | false | Force reinstall xformers during environment prep |
| `--reinstall-torch` | bool | false | Force reinstall PyTorch during environment prep |
| `--update-check` | bool | false | Check for WebUI updates at startup |
| `--test-server` | bool | false | Configure for automated testing |
| `--log-startup` | bool | false | Log detailed timing for startup phases |
| `--skip-prepare-environment` | bool | false | Skip all environment preparation (deps, repos) |
| `--skip-install` | bool | false | Skip pip install steps |
| `--dump-sysinfo` | bool | false | Dump system info JSON and exit |
| `--loglevel` | str | None | Set Python logging level |
| `--skip-version-check` | bool | false | Skip torch/xformers version compatibility check |

#### Model & Checkpoint Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--config` | str | `configs/v1-inference.yaml` | Model architecture config file |
| `--ckpt` | str | `model.ckpt` | Checkpoint file to load at startup |
| `--ckpt-dir` | str | None | Directory for checkpoint file discovery |
| `--vae-dir` | str | None | Directory for VAE file discovery |
| `--vae-path` | str | None | Specific VAE checkpoint to load |
| `--no-download-sd-model` | bool | false | Do not download the default SD model if missing |
| `--do-not-download-clip` | bool | false | Do not download CLIP model even if missing |
| `--no-hashing` | bool | false | Disable SHA256 hashing of checkpoints |
| `--skip-load-model-at-start` | bool | false | Start without loading any model (load on first generation) |

#### Performance & Memory Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--no-half` | bool | false | Use full float32 precision (doubles VRAM usage) |
| `--no-half-vae` | bool | false | Use float32 for VAE only (fixes black image issues) |
| `--precision` | str | `autocast` | Force precision: `full` or `autocast` |
| `--upcast-sampling` | bool | false | Upcast sampling to float32 (less VRAM than `--no-half`, better quality) |
| `--medvram` | bool | false | Partial VRAM offload: move cond/uncond models to CPU during generation |
| `--medvram-sdxl` | bool | false | SDXL-specific medvram: only activate for SDXL models |
| `--lowvram` | bool | false | Aggressive VRAM offload: move individual UNet modules sequentially |
| `--lowram` | bool | false | Load checkpoint weights to VRAM instead of RAM first |
| `--xformers` | bool | false | Enable xformers memory-efficient attention |
| `--force-enable-xformers` | bool | false | Enable xformers even if version check fails |
| `--xformers-flash-attention` | bool | false | Use xformers flash attention (requires compatible hardware) |
| `--opt-split-attention` | bool | false | Doggettx cross-attention optimization (auto-enabled for CUDA) |
| `--opt-sub-quad-attention` | bool | false | Sub-quadratic attention: memory-efficient, configurable chunk sizes |
| `--sub-quad-q-chunk-size` | int | 1024 | Query chunk size for sub-quadratic attention |
| `--sub-quad-kv-chunk-size` | int | 512 | Key/value chunk size for sub-quadratic attention |
| `--sub-quad-chunk-threshold` | int | 80 | Threshold percentage for chunking in sub-quadratic attention |
| `--opt-split-attention-invokeai` | bool | false | InvokeAI cross-attention optimization |
| `--opt-split-attention-v1` | bool | false | Original v1 cross-attention optimization |
| `--opt-sdp-attention` | bool | false | Scaled dot product attention (PyTorch 2.0+) |
| `--opt-sdp-no-mem-attention` | bool | false | SDP attention without memory-efficient variant |
| `--disable-opt-split-attention` | bool | false | Disable all automatic attention optimizations |
| `--opt-channelslast` | bool | false | Use channels-last memory format for tensors |
| `--disable-model-loading-ram-optimization` | bool | false | Disable RAM optimization during model loading |
| `--use-cpu` | list | [] | Force CPU for specific operations (e.g., `all`, `sd`, `interrogate`) |
| `--use-ipex` | bool | false | Use Intel IPEX for Intel XPU acceleration |

#### Network & Server Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--listen` | bool | false | Listen on 0.0.0.0 instead of 127.0.0.1 |
| `--port` | int | 7860 | Server port |
| `--server-name` | str | None | Custom server hostname |
| `--share` | bool | false | Create a Gradio public share link |
| `--ngrok` | str | None | ngrok auth token for tunneling |
| `--ngrok-options` | dict | `{}` | Additional ngrok tunnel options (JSON) |
| `--cors-allow-origins` | str | None | Comma-separated allowed CORS origins |
| `--cors-allow-origins-regex` | str | None | Regex pattern for CORS origin matching |
| `--tls-keyfile` | str | None | Path to TLS private key file |
| `--tls-certfile` | str | None | Path to TLS certificate file |
| `--disable-tls-verify` | bool | false | Skip TLS certificate verification for HTTPS |
| `--subpath` | str | None | URL subpath for reverse proxy (e.g., `/sd`) |
| `--timeout-keep-alive` | int | 30 | Uvicorn keep-alive timeout in seconds |
| `--no-gradio-queue` | bool | false | Disable Gradio request queuing |

#### Authentication Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--gradio-auth` | str | None | Gradio login credentials (`user:pass` or `u1:p1,u2:p2`) |
| `--gradio-auth-path` | str | None | Path to file with Gradio credentials (one `user:pass` per line) |
| `--api-auth` | str | None | API Basic auth credentials (`user:pass` or `u1:p1,u2:p2`) |
| `--enable-insecure-extension-access` | bool | false | Allow Extensions tab without `--share` |
| `--administrator` | bool | false | Mark this session as administrator (Settings tab access) |

#### UI Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--theme` | str | None | Gradio theme (e.g., `dark`) |
| `--autolaunch` | bool | false | Open browser automatically on startup |
| `--ui-config-file` | str | `ui-config.json` | UI component defaults file |
| `--ui-settings-file` | str | `config.json` | Settings/options persistence file |
| `--hide-ui-dir-config` | bool | false | Hide directory path inputs in the UI |
| `--freeze-settings` | bool | false | Prevent all settings from being modified via UI |
| `--freeze-settings-in-sections` | str | None | Freeze specific settings sections (comma-separated) |
| `--freeze-specific-settings` | str | None | Freeze individual settings by name (comma-separated) |
| `--use-textbox-seed` | bool | false | Use text input for seed instead of number input |
| `--disable-console-progressbars` | bool | false | Suppress progress bars in the terminal |
| `--no-progressbar-hiding` | bool | false | Keep the progress bar visible in UI at all times |
| `--gradio-debug` | bool | false | Enable Gradio debug mode |
| `--gradio-allowed-path` | list | [] | Additional filesystem paths Gradio can serve |
| `--ui-debug-mode` | bool | false | UI debug mode (no model load, fast startup) |
| `--styles-file` | list | `[styles.csv]` | Prompt styles file(s) |
| `--filenames-max-length` | int | 128 | Maximum output filename length |
| `--unix-filenames-sanitization` | bool | false | Use Unix-style filename sanitization |
| `--no-prompt-history` | bool | false | Disable prompt history dropdown |

#### API Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--api` | bool | false | Enable the REST API alongside the UI |
| `--api-auth` | str | None | API HTTP Basic auth (`user:pass`) |
| `--api-log` | bool | false | Log all API requests |
| `--nowebui` | bool | false | API-only mode (no Gradio UI) |
| `--api-server-stop` | bool | false | Enable server-kill/restart/stop API endpoints |

#### Path Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--data-dir` | str | `(repo root)` | Base directory for all data (models, outputs, config) |
| `--models-dir` | str | `models` | Directory containing model subdirectories |
| `--embeddings-dir` | str | `embeddings` | Textual inversion embeddings directory |
| `--textual-inversion-templates-dir` | str | `textual_inversion_templates` | Training templates directory |
| `--hypernetwork-dir` | str | `models/hypernetworks` | Hypernetworks directory |
| `--localizations-dir` | str | `localizations` | UI translation files directory |
| `--gfpgan-dir` | str | `GFPGAN` | GFPGAN model directory |
| `--gfpgan-model` | str | None | GFPGAN model filename |
| `--codeformer-models-path` | str | `models/Codeformer` | CodeFormer models directory |
| `--gfpgan-models-path` | str | `models/GFPGAN` | GFPGAN models directory |
| `--esrgan-models-path` | str | `models/ESRGAN` | ESRGAN models directory |
| `--bsrgan-models-path` | str | `models/BSRGAN` | BSRGAN models directory |
| `--realesrgan-models-path` | str | `models/RealESRGAN` | RealESRGAN models directory |
| `--dat-models-path` | str | `models/DAT` | DAT models directory |
| `--clip-models-path` | str | None | CLIP models directory |
| `--swinir-models-path` | str | `models/SwinIR` | SwinIR models directory |
| `--ldsr-models-path` | str | `models/LDSR` | LDSR models directory |
| `--scunet-models-path` | str | `models/ScuNET` | ScuNET models directory |
| `--lora-dir` | str | `models/Lora` | LoRA models directory |
| `--lyco-dir-backcompat` | str | `models/LyCORIS` | LyCORIS backward-compatible directory |

#### Extension Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--disable-all-extensions` | bool | false | Disable all extensions (built-in and extra) |
| `--disable-extra-extensions` | bool | false | Disable only user-installed extensions |
| `--enable-insecure-extension-access` | bool | false | Allow extension install/update from the UI |

#### Safety Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--disable-safe-unpickle` | bool | false | Disable the safe unpickler for model loading |
| `--disable-nan-check` | bool | false | Skip NaN checks on generated images |
| `--allow-code` | bool | false | Allow execution of custom code from prompts/scripts |
| `--device-id` | int | None | Select specific CUDA device by ID |

#### Deprecated / No-Op Flags

These flags are accepted for backward compatibility but perform no action:

| Flag | Notes |
|------|-------|
| `--max-batch-count` | Replaced by UI setting |
| `--always-batch-cond-uncond` | Now always active |
| `--unload-gfpgan` | No longer needed |
| `--deepdanbooru` | Removed feature |
| `--ngrok-region` | No longer used by ngrok |
| `--show-negative-prompt` | Always shown |
| `--enable-console-prompts` | Removed |
| `--gradio-img2img-tool` | Fixed implementation |
| `--gradio-inpaint-tool` | Fixed implementation |
| `--gradio-queue` | Queue is always active |
| `--add-stop-route` | Replaced by `--api-server-stop` |

> [!IMPORTANT]
> When using `webui-user.sh` or `webui-user.bat`, set flags via the `COMMANDLINE_ARGS` environment variable rather than passing them directly to the script. Example: `export COMMANDLINE_ARGS="--xformers --api --listen"`.

### 3.2 Environment Variables

All environment variables read during startup, primarily in `modules/launch_utils.py` and `webui.py`.

| Variable | Default | Source File | Description |
|----------|---------|-------------|-------------|
| `COMMANDLINE_ARGS` | (empty) | `webui-user.sh/bat` | CLI flags passed to `launch.py` |
| `TORCH_COMMAND` | auto-detected | `launch_utils.py` | Full pip install command for PyTorch |
| `TORCH_INDEX_URL` | `https://download.pytorch.org/whl/cu121` | `launch_utils.py` | PyTorch wheel index URL |
| `REQS_FILE` | `requirements_versions.txt` | `launch_utils.py` | pip requirements file |
| `XFORMERS_PACKAGE` | `xformers==0.0.23.post1` | `launch_utils.py` | xformers package specifier |
| `CLIP_PACKAGE` | `https://github.com/openai/CLIP/...` | `launch_utils.py` | CLIP model repository URL |
| `OPENCLIP_PACKAGE` | `https://github.com/mlfoundations/open_clip/...` | `launch_utils.py` | OpenCLIP repository URL |
| `STABLE_DIFFUSION_REPO` | `https://github.com/Stability-AI/stablediffusion.git` | `launch_utils.py` | Stable Diffusion repository URL |
| `STABLE_DIFFUSION_XL_REPO` | `https://github.com/Stability-AI/generative-models.git` | `launch_utils.py` | SDXL repository URL |
| `K_DIFFUSION_REPO` | `https://github.com/crowsonkb/k-diffusion.git` | `launch_utils.py` | k-diffusion repository URL |
| `BLIP_REPO` | `https://github.com/salesforce/BLIP.git` | `launch_utils.py` | BLIP repository URL |
| `ASSETS_REPO` | `https://github.com/AUTOMATIC1111/stable-diffusion-webui-assets.git` | `launch_utils.py` | WebUI assets repository URL |
| `STABLE_DIFFUSION_COMMIT_HASH` | (pinned) | `launch_utils.py` | Pinned commit for SD repo |
| `STABLE_DIFFUSION_XL_COMMIT_HASH` | (pinned) | `launch_utils.py` | Pinned commit for SDXL repo |
| `K_DIFFUSION_COMMIT_HASH` | (pinned) | `launch_utils.py` | Pinned commit for k-diffusion |
| `BLIP_COMMIT_HASH` | (pinned) | `launch_utils.py` | Pinned commit for BLIP |
| `ASSETS_COMMIT_HASH` | (pinned) | `launch_utils.py` | Pinned commit for assets |
| `GIT` | `git` | `launch_utils.py` | Git executable path |
| `INDEX_URL` | (empty) | `launch_utils.py` | Custom pip index URL (`--index-url` for all pip installs) |
| `SD_WEBUI_CACHE_FILE` | `cache.json` | `cache.py` | Cache data file path |
| `SD_WEBUI_CACHE_DIR` | (empty) | `cache.py` | Cache directory override |
| `SD_WEBUI_LOG_LEVEL` | (empty) | `initialize.py` | Python logging level (DEBUG, INFO, WARNING, etc.) |
| `SD_WEBUI_RICH_LOG` | (empty) | `initialize.py` | Enable rich formatted logging |
| `SD_WEBUI_RESTARTING` | (empty) | `webui.py` | Set to `1` during restart to skip re-initialization |
| `SD_WEBUI_RESTART` | (empty) | `webui.py` | File path to write for restart signaling |
| `WEBUI_LAUNCH_LIVE_OUTPUT` | `1` | `launch_utils.py` | Show live output during dependency installation |
| `WEBUI_EXTENSIONS_INDEX` | `https://raw.githubusercontent.com/.../index.json` | `launch_utils.py` | Extensions registry index URL |
| `GRADIO_TEMP_DIR` | (system temp) | `initialize_util.py` | Custom temporary directory for Gradio |
| `HF_ENDPOINT` | `https://huggingface.co` | `launch_utils.py` | HuggingFace endpoint URL (for mirrors/proxies) |
| `WEBUI_RICH_EXCEPTIONS` | (empty) | `initialize.py` | Enable rich exception formatting |
| `IGNORE_CMD_ARGS_ERRORS` | (empty) | `cmd_args.py` | Suppress argparse errors (useful for embedding) |
| `COVERAGE_RUN` | (empty) | `launch_utils.py` | Set during test coverage runs |
| `ACCELERATE` | (empty) | `launch_utils.py` | Use HuggingFace Accelerate for launching |
| `NO_TCMALLOC` | (empty) | `launch_utils.py` | Disable TCMalloc on Linux |
| `CUDA_VISIBLE_DEVICES` | (unset) | PyTorch | Restrict visible GPUs (standard CUDA var) |
| `venv_dir` | `venv` | `webui-user.sh/bat` | Virtual environment directory name |
| `python_cmd` | `python3` | `webui-user.sh/bat` | Python executable |
| `git_cmd` | `git` | `webui-user.sh/bat` | Git executable |

> [!TIP]
> To use a Chinese HuggingFace mirror, set `HF_ENDPOINT=https://hf-mirror.com` in your environment. This routes all model downloads through the mirror without modifying any source files.

### 3.3 Configuration Files

#### config.json

Auto-generated settings file storing all values from the Settings tab. Created on first run, updated when the user saves settings. Contains hundreds of keys covering every UI-configurable option: sampler defaults, output paths, face restoration preferences, upscaler settings, UI appearance, and model behavior. This file is the runtime configuration database.

Key sections include:
- `samples_save`, `samples_format` — output saving behavior
- `grid_save`, `grid_format` — grid image settings
- `outdir_txt2img_samples`, `outdir_img2img_samples` — output directories
- `sd_model_checkpoint` — currently selected model
- `sd_vae` — currently selected VAE
- `CLIP_stop_at_last_layers` — CLIP skip setting
- `eta_noise_seed_delta` — ENSD (affects reproducibility across samplers)

#### ui-config.json

Controls default values and visibility of individual Gradio UI components. Each key maps to a specific component path (e.g., `txt2img/Width/value: 512`). Can lock components by adding `/visible`, `/minimum`, `/maximum` entries.

#### styles.csv

Prompt style library with columns: `name`, `prompt`, `negative_prompt`. Styles can use `{prompt}` as a placeholder for the user's input prompt.

#### configs/*.yaml

Model architecture definitions used during checkpoint loading:

| File | Architecture |
|------|-------------|
| `v1-inference.yaml` | Stable Diffusion v1.x (512x512) |
| `v1-inpainting-inference.yaml` | SD v1.x inpainting variant |
| `v2-inference.yaml` | Stable Diffusion v2.0 (512x512) |
| `v2-inference-v.yaml` | SD v2.0 v-prediction (768x768) |
| `v2-inpainting-inference.yaml` | SD v2.0 inpainting |
| `sd_xl_base.yaml` | SDXL Base |
| `sd_xl_refiner.yaml` | SDXL Refiner |
| `sd_xl_inpaint.yaml` | SDXL Inpainting |
| `sd3-inference.yaml` | Stable Diffusion 3 |
| `instruct-pix2pix.yaml` | InstructPix2Pix |
| `alt-diffusion-inference.yaml` | AltDiffusion variants |

---

## 4. Deployment & Scaling

### Single-User Local Deployment (Default)

The default configuration binds to `127.0.0.1:7860`, accessible only from the local machine. Start with:

```bash
./webui.sh
# or on Windows:
webui-user.bat
```

No additional configuration is needed. The browser opens automatically with `--autolaunch`.

### Network-Accessible Deployment

To serve the UI to other machines on the local network:

```bash
export COMMANDLINE_ARGS="--listen --port 7860"
./webui.sh
```

The `--listen` flag binds to `0.0.0.0`. Combine with `--gradio-auth` to require login credentials when exposing on a network.

For internet access without a reverse proxy, Gradio's built-in share links provide temporary public URLs:

```bash
export COMMANDLINE_ARGS="--share"
./webui.sh
```

This creates a `*.gradio.live` tunnel valid for 72 hours.

For persistent tunneling via ngrok:

```bash
export COMMANDLINE_ARGS="--ngrok YOUR_AUTH_TOKEN --ngrok-options '{\"hostname\": \"your-domain.ngrok.io\"}'"
```

### Reverse Proxy Setup

When deploying behind nginx, Apache, or Traefik with a URL subpath:

```bash
export COMMANDLINE_ARGS="--subpath /stable-diffusion --listen --port 7860"
```

Example nginx configuration:

```nginx
location /stable-diffusion/ {
    proxy_pass http://127.0.0.1:7860/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 300s;
}
```

> [!WARNING]
> The `--subpath` flag is necessary when WebUI is not served at the root path. Without it, internal Gradio API calls and static asset paths will break silently.

### TLS Configuration

For direct HTTPS termination (without a reverse proxy handling TLS):

```bash
export COMMANDLINE_ARGS="--tls-keyfile /path/to/key.pem --tls-certfile /path/to/cert.pem --listen"
```

The `--disable-tls-verify` flag disables certificate verification for outgoing HTTPS connections (e.g., downloading models). Use only in air-gapped environments with self-signed certificates.

### API-Only Mode

Run without the Gradio UI for pure API access (lower resource usage, suitable for backend integration):

```bash
export COMMANDLINE_ARGS="--nowebui --api --listen --port 7860"
```

In this mode, only the FastAPI endpoints under `/sdapi/v1/` are available. The Gradio interface is not loaded. Auto-generated API documentation is available at `/docs` (Swagger) and `/redoc`.

### Process Management

The `--api-server-stop` flag enables three management endpoints:

- `POST /sdapi/v1/server-restart` — Graceful restart (reloads models and extensions)
- `POST /sdapi/v1/server-stop` — Graceful shutdown
- `POST /sdapi/v1/server-kill` — Immediate termination

Without this flag, these endpoints return 403.

> [!CAUTION]
> The `--api-server-stop` flag should only be enabled in trusted environments. Combined with `--api` without `--api-auth`, it allows unauthenticated remote server shutdown.

---

## 5. Operations

### Startup Flow

The complete startup sequence:

```
1. webui.sh / webui.bat
   └── Sources webui-user.sh / webui-user.bat (sets env vars)

2. launch.py
   ├── Parses --skip-prepare-environment
   └── Calls launch_utils.prepare_environment()
        ├── Checks Python version (3.10.6+)
        ├── Checks git version
        ├── Commits current repo hash
        ├── Clones/updates sub-repos (SD, SDXL, k-diffusion, BLIP, assets)
        ├── Installs PyTorch (TORCH_COMMAND)
        ├── Installs xformers (if --xformers)
        ├── pip install -r requirements_versions.txt
        └── Runs extension install.py scripts

3. webui.py → webui()
   ├── initialize.imports()          — patch Gradio, fix imports
   ├── initialize.check_versions()   — validate torch/xformers compat
   ├── initialize.initialize()       — load options, extensions, model
   │    ├── Load config.json (settings)
   │    ├── Load extensions
   │    ├── Run extension callbacks (app_started)
   │    └── Load SD model checkpoint → GPU
   ├── Create Gradio Blocks UI (modules/ui.py)
   ├── Create API (modules/api/api.py)
   ├── Setup middleware (CORS, gzip, upload size)
   └── app.launch() → Uvicorn server on configured host:port

4. Server running, accepting requests
```

> [!NOTE]
> The `--log-startup` flag wraps each startup phase in a timer, printing elapsed time to the console. Useful for diagnosing slow startups caused by model loading, extension installation, or network access.

### Restart Mechanism

The application supports in-process restart via a file-based signaling mechanism:

1. A restart is requested (via UI button or API `POST /sdapi/v1/server-restart`)
2. `shared.state.server_command = "restart"` is set
3. The Gradio server shuts down
4. `webui.py` detects the restart command in its main loop
5. Sets `SD_WEBUI_RESTARTING=1` in the environment
6. Re-enters the startup sequence, skipping environment preparation
7. On Unix: writes a signal file (path from `SD_WEBUI_RESTART` env var) that `webui.sh` monitors to re-launch the process

### Extension Management

Extensions are discovered from two locations:
- `extensions/` — user-installed extensions
- `extensions-builtin/` — shipped with the WebUI

Each extension is a directory containing at minimum a `scripts/` folder (for Script-based extensions) or any Python files that register via `script_callbacks`.

Extension lifecycle operations:
- **Install**: Clone a git repo into `extensions/`, run its `install.py` if present
- **Update**: `git pull` within the extension directory
- **Enable/Disable**: Toggle in `config.json` under `disabled_extensions` list
- **Config state backup/restore**: The system can snapshot and restore the full `config.json` state via the settings UI

> [!TIP]
> Use `--disable-extra-extensions` to start with only built-in extensions when debugging extension conflicts. This leaves `extensions-builtin/` active but disables everything in `extensions/`.

### Model Management

**Checkpoint discovery**: On startup and when refreshed, the system scans `--ckpt-dir` (defaults to `models/Stable-diffusion/`) for `.ckpt`, `.safetensors`, and `.pt` files. Each discovered model is wrapped in a `CheckpointInfo` object with its path, hash, title, and architecture config.

**Model loading**: `sd_models.load_model()` reads the checkpoint, applies the architecture config, loads weights to the appropriate device, and stores the result in `shared.sd_model`. The hijack system then patches the model's forward methods.

**VAE loading**: VAEs are independently swappable. `sd_vae.py` manages a separate VAE registry and can override the checkpoint's built-in VAE at load time or on-the-fly.

**Model merging**: The built-in Checkpoint Merger tab supports weighted merge, add difference, and other interpolation methods between two or three checkpoints.

### Cache System

The WebUI uses `diskcache` for persistent caching with subsection-based organization. Each cache subsection has a 4 GB size limit. Cached items include:
- Checkpoint hashes (avoid recomputing SHA256 on every startup)
- Model metadata
- Extension index data

Cache location defaults to `cache.json` in the data directory, overridden by `SD_WEBUI_CACHE_FILE` or `SD_WEBUI_CACHE_DIR`.

### Logging

| Mechanism | Configuration | Detail |
|-----------|--------------|--------|
| Console logging | `SD_WEBUI_LOG_LEVEL` env var | Standard Python logging levels |
| Rich logging | `SD_WEBUI_RICH_LOG=1` | Colored, formatted console output |
| API request logging | `--api-log` | Logs all API request/response pairs |
| Startup timing | `--log-startup` | Phase-by-phase timing output |
| Rich exceptions | `WEBUI_RICH_EXCEPTIONS=1` | Detailed exception formatting |

### Memory Monitoring

A background `MemUsageMonitor` thread continuously tracks GPU memory usage. This data is exposed via:
- The progress bar overlay in the UI
- `GET /sdapi/v1/memory` API endpoint (returns free/used/total for each device)
- Console output (when not suppressed)

The poll interval is configurable via the `memmon_poll_rate` setting in `config.json`.

---

## 6. Performance

### Attention Optimization Hierarchy

The choice of cross-attention implementation is the single largest performance lever. The system selects optimizations in the following priority order:

| Priority | Optimization | Flag | VRAM Reduction | Speed |
|----------|-------------|------|----------------|-------|
| 1 | xformers | `--xformers` | High | Fastest |
| 2 | Scaled Dot Product (SDP) | `--opt-sdp-attention` | Moderate | Fast (PyTorch 2.0+) |
| 3 | Sub-quadratic | `--opt-sub-quad-attention` | Configurable | Moderate |
| 4 | InvokeAI | `--opt-split-attention-invokeai` | Moderate | Moderate |
| 5 | Doggettx | `--opt-split-attention` | Moderate | Moderate |
| 6 | v1 split | `--opt-split-attention-v1` | Moderate | Slower |
| 7 | None | `--disable-opt-split-attention` | None | Baseline |

On CUDA devices, Doggettx (`--opt-split-attention`) is auto-enabled if no other optimization is selected. On non-CUDA platforms, no optimization is auto-selected.

> [!NOTE]
> SDP attention (`--opt-sdp-attention`) requires PyTorch 2.0 or later. It provides native attention optimization without the xformers dependency, making it the recommended option for systems where xformers installation fails.

### Memory Tiers

Three tiers of VRAM management for different hardware capabilities:

**`--lowvram`** (4-6 GB VRAM): Moves individual UNet modules to GPU one at a time during the forward pass. Each layer is loaded, executed, then moved back to CPU. Extremely slow but functional on low-end GPUs. Implemented in `modules/lowvram.py` by registering forward hooks on every `CrossAttention` and `ResBlock` module.

**`--medvram`** (6-8 GB VRAM): Splits the generation pipeline into stages. The text encoder (CLIP) runs first and is moved to CPU, then the UNet runs the diffusion loop, then the VAE decodes the final latent. Only one major component occupies VRAM at a time.

**`--medvram-sdxl`**: A variant of `--medvram` that only activates the medvram behavior when an SDXL model is loaded. Standard SD 1.x/2.x models run at full speed without offloading.

**Default** (8+ GB VRAM): All model components remain in VRAM simultaneously for maximum throughput.

### Additional Performance Options

**Half-precision**: Enabled by default. All model weights and computations use float16, halving VRAM usage versus float32. Disable with `--no-half` for maximum quality or to fix rare NaN issues. `--no-half-vae` applies float32 only to the VAE (fixes black/green image artifacts with certain VAEs while keeping the UNet in float16).

**`--upcast-sampling`**: Performs the sampling loop in float32 while keeping model weights in float16. Uses less additional VRAM than `--no-half` while addressing most precision-related artifacts.

**`--opt-channelslast`**: Converts tensors to channels-last memory format (`NHWC`), which can improve performance on certain NVIDIA architectures by better matching hardware memory access patterns.

**Token merging** (tomesd): Reduces the number of tokens processed by the transformer blocks by merging similar tokens. Configurable ratio in Settings. Higher ratio = faster generation, slight quality loss.

**HyperTile**: Built-in extension that tiles attention computation for significant speedup at higher resolutions (1024x1024+). Configurable tile size in Settings.

**TCMalloc**: On Linux, the launcher automatically detects and uses Google's TCMalloc memory allocator if available, which reduces memory fragmentation for long-running sessions. Disable with `NO_TCMALLOC=1`.

---

## 7. Security

### Safe Unpickle (modules/safe.py)

The primary security mechanism protecting against malicious model files. Python pickle files can execute arbitrary code during deserialization. The `RestrictedUnpickler` class in `safe.py` maintains an allowlist of safe globals and blocks all others.

The safe unpickler:
- Intercepts all `torch.load()` calls via monkey-patching
- Validates every class reference against the allowlist before instantiation
- Scans `.pt` and `.ckpt` files for dangerous patterns before loading
- Raises `pickle.UnpicklingError` if a blocked global is encountered

> [!WARNING]
> The `--disable-safe-unpickle` flag removes all model file security scanning. A malicious `.ckpt` file loaded with this flag can execute arbitrary code on your system, including installing malware, stealing credentials, or destroying data. Never disable this protection when loading models from untrusted sources.

### Authentication

**Gradio Authentication**: Protects the web interface with username/password login.

```bash
# Inline credentials
--gradio-auth "admin:secretpassword"

# Multiple users
--gradio-auth "user1:pass1,user2:pass2"

# From file (one user:pass per line)
--gradio-auth-path /path/to/credentials.txt
```

**API Authentication**: Protects the `/sdapi/v1/` endpoints with HTTP Basic auth.

```bash
--api-auth "apiuser:apipassword"
```

When `--api-auth` is set, all API requests must include an `Authorization: Basic <base64>` header.

> [!CAUTION]
> Neither Gradio auth nor API auth uses encrypted password storage. Credentials are compared as plaintext. Always use TLS (`--tls-keyfile`/`--tls-certfile` or a reverse proxy) when authentication is enabled on a network-accessible instance.

### CORS Policy

The WebUI actively hardens CORS beyond Gradio's defaults. During initialization (`initialize_util.py`), the default Gradio CORS middleware is removed and replaced with a restrictive policy. Additional origins are allowed only via:

- `--cors-allow-origins "https://example.com,https://other.com"` — explicit whitelist
- `--cors-allow-origins-regex "https://.*\.example\.com"` — pattern matching

Without these flags, cross-origin requests to the API are blocked.

### Extension Security

The Extensions tab (install/update extensions from the UI) is disabled by default when `--share` is not used. Enable it with `--enable-insecure-extension-access`.

Extensions run arbitrary Python code with full access to the process. They can:
- Access the filesystem
- Make network requests
- Modify model behavior
- Intercept generated images

Only install extensions from trusted sources.

### URL Verification for API Image Fetching

The API's image-fetching functionality (used when providing image URLs in API requests) has two relevant settings:
- `api_enable_requests` — enables fetching images from URLs (default: true)
- `api_forbid_local_requests` — blocks requests to localhost/private IPs to prevent SSRF (default: true)

### Known Security Issues

**Dead repository URLs (GitHub issue #17343)**: Some repository URLs in `launch_utils.py` point to repositories that could potentially be re-registered by a third party, creating a supply-chain attack vector for credential harvesting or code injection during environment preparation.

**Pickle deserialization concerns (GitHub issue #17322)**: While `safe.py` mitigates the primary risk, the allowlist-based approach requires ongoing maintenance as new attack patterns emerge. The safetensors format (`.safetensors`) is inherently safe and should be preferred over `.ckpt` files.

### The `--allow-code` Flag

This flag enables execution of custom Python code from within the interface. It is intended only for development and testing.

> [!WARNING]
> Never enable `--allow-code` on a network-accessible instance. It grants arbitrary code execution to anyone with UI or API access.

---

## 8. Developer Internals

### 8.1 Repository Structure

```
stable-diffusion-webui/
├── launch.py                    Entry point
├── webui.py                     Application core (init, server, restart loop)
├── modules/                     Core application modules
│   ├── api/                     REST API
│   │   ├── api.py               API class, route definitions (35+ endpoints)
│   │   └── models.py            Pydantic request/response models
│   ├── textual_inversion/       Textual inversion training
│   │   ├── textual_inversion.py Training logic
│   │   ├── dataset.py           Training dataset
│   │   ├── learn_schedule.py    Learning rate scheduling
│   │   ├── image_embedding.py   Embedding in images
│   │   ├── logging.py           Training logging
│   │   └── preprocess.py        Image preprocessing
│   ├── hypernetworks/           Hypernetwork training
│   │   ├── hypernetwork.py      Hypernetwork architecture and training
│   │   └── ui.py                Training UI
│   ├── processing.py            Core generation pipeline
│   ├── sd_models.py             Checkpoint management
│   ├── sd_models_config.py      Model config resolution
│   ├── sd_models_xl.py          SDXL-specific model logic
│   ├── sd_samplers.py           Sampler registry
│   ├── sd_samplers_kdiffusion.py    k-diffusion sampler wrapper
│   ├── sd_samplers_timesteps.py     Timestep-based samplers
│   ├── sd_samplers_common.py        Shared sampler utilities
│   ├── sd_samplers_lcm.py           LCM sampler support
│   ├── sd_samplers_extra.py         Additional samplers
│   ├── sd_schedulers.py         Noise schedulers
│   ├── sd_vae.py                VAE management
│   ├── sd_vae_approx.py         Approximate VAE (fast preview)
│   ├── sd_vae_taesd.py          Tiny AutoEncoder for SD (fast preview)
│   ├── sd_hijack.py             Model hijacking system
│   ├── sd_hijack_clip.py        CLIP model hijacking
│   ├── sd_hijack_open_clip.py   OpenCLIP hijacking
│   ├── sd_hijack_unet.py        UNet hijacking
│   ├── sd_hijack_optimizations.py   Attention optimizations
│   ├── sd_hijack_xlmr.py        XLM-RoBERTa hijacking
│   ├── sd_emphasis.py           Prompt emphasis implementations
│   ├── sd_disable_initialization.py  Disable weight init for fast load
│   ├── scripts.py               Script system (base class, runner)
│   ├── script_callbacks.py      Extension callback system
│   ├── extensions.py            Extension management
│   ├── extra_networks.py        Extra network system (LoRA, etc.)
│   ├── extra_networks_hypernet.py   Hypernetwork extra network
│   ├── shared.py                Global state (opts, state, sd_model)
│   ├── shared_cmd_options.py    Shared command option handling
│   ├── shared_gradio_themes.py  Gradio theme definitions
│   ├── shared_init.py           Shared initialization
│   ├── shared_items.py          Shared UI items
│   ├── shared_options.py        Settings option definitions
│   ├── shared_state.py          State class (progress, interrupts)
│   ├── shared_total_tqdm.py     Global tqdm progress
│   ├── options.py               Options/OptionInfo system
│   ├── cmd_args.py              CLI argument definitions
│   ├── launch_utils.py          Environment preparation
│   ├── initialize.py            Startup initialization
│   ├── initialize_util.py       Startup utilities
│   ├── ui.py                    Gradio UI construction
│   ├── ui_common.py             Shared UI components
│   ├── ui_components.py         Custom Gradio components
│   ├── ui_extra_networks.py     Extra networks UI
│   ├── ui_extra_networks_user_metadata.py  User metadata UI
│   ├── ui_extra_networks_checkpoints.py    Checkpoint cards UI
│   ├── ui_extensions.py         Extensions tab UI
│   ├── ui_loadsave.py           UI state persistence
│   ├── ui_postprocessing.py     Extras tab UI
│   ├── ui_prompt_styles.py      Styles UI
│   ├── ui_settings.py           Settings tab UI
│   ├── ui_tempdir.py            Temp directory management
│   ├── images.py                Image saving, grids, filenames
│   ├── prompt_parser.py         Prompt syntax parser
│   ├── postprocessing.py        Postprocessing pipeline
│   ├── upscaler.py              Upscaler base and registry
│   ├── safe.py                  Safe model unpickling
│   ├── call_queue.py            Generation queue (FIFO lock)
│   ├── progress.py              Task progress tracking
│   ├── cache.py                 Diskcache wrapper
│   ├── devices.py               Device/dtype management
│   ├── paths.py                 Path resolution (external repos)
│   ├── paths_internal.py        Internal path constants
│   ├── styles.py                Prompt style database
│   ├── infotext_utils.py        Generation parameter parsing
│   ├── infotext_versions.py     Parameter version handling
│   ├── sysinfo.py               System info dump
│   ├── lowvram.py               Low VRAM module offloading
│   ├── interrogate.py           CLIP/BLIP interrogation
│   ├── memmon.py                Memory monitoring thread
│   ├── timer.py                 Startup timing
│   ├── errors.py                Error handling, exception display
│   ├── fifo_lock.py             FIFO fair lock implementation
│   ├── generation_parameters_copypaste.py  Parameter copy/paste
│   ├── modelloader.py           Model file discovery
│   ├── img2img.py               img2img pipeline
│   ├── txt2img.py               txt2img pipeline
│   ├── masking.py               Inpainting mask processing
│   └── ...
├── extensions-builtin/          Built-in extensions
│   ├── Lora/                    LoRA/LyCORIS support
│   │   ├── networks/            Network implementations
│   │   │   ├── lora.py          Standard LoRA
│   │   │   ├── hada.py          LoHa (Hadamard)
│   │   │   ├── lokr.py          LoKr (Kronecker)
│   │   │   ├── ia3.py           IA3
│   │   │   ├── oft.py           OFT (Orthogonal Fine-Tuning)
│   │   │   ├── glora.py         GLoRA
│   │   │   ├── full.py          Full network
│   │   │   └── norm.py          Norm network
│   │   ├── network.py           Base network class
│   │   └── extra_networks_lora.py  Prompt activation (<lora:name:weight>)
│   ├── LDSR/                    Latent Diffusion Super Resolution
│   ├── hypertile/               HyperTile attention optimization
│   ├── ScuNET/                  ScuNET denoising
│   ├── SwinIR/                  SwinIR upscaling
│   ├── prompt-bracket-checker/  Bracket matching validation
│   ├── extra-options-section/   Additional generation options
│   ├── postprocessing-caption/  Auto-captioning
│   ├── mobile/                  Mobile UI optimizations
│   ├── canvas-zoom-and-pan/     Canvas interaction
│   ├── soft-inpainting/         Soft inpainting
│   └── forge_preprocessor_normalbae/  Normal/BAE preprocessing
├── extensions/                  User-installed extensions (gitignored)
├── models/                      Model storage
│   ├── Stable-diffusion/        SD checkpoints
│   ├── VAE/                     VAE models
│   ├── Lora/                    LoRA models
│   ├── ESRGAN/                  ESRGAN upscalers
│   ├── RealESRGAN/              RealESRGAN upscalers
│   ├── hypernetworks/           Hypernetworks
│   ├── GFPGAN/                  GFPGAN face restoration
│   ├── Codeformer/              CodeFormer face restoration
│   ├── SwinIR/                  SwinIR models
│   ├── LDSR/                    LDSR models
│   ├── ScuNET/                  ScuNET models
│   ├── BSRGAN/                  BSRGAN models
│   ├── DAT/                     DAT models
│   └── LyCORIS/                 LyCORIS models
├── configs/                     Model architecture YAML files
├── embeddings/                  Textual inversion embeddings
├── outputs/                     Generated images (default)
├── textual_inversion_templates/ TI training templates
├── localizations/               UI translation files
├── test/                        Test suite
├── javascript/                  Frontend JavaScript
├── script.js                    Main frontend script
├── style.css                    Custom CSS
├── requirements.txt             Base requirements
├── requirements_versions.txt    Pinned requirements
└── environment-wsl2.yaml        Conda environment for WSL2
```

### 8.2 Module Reference

#### modules/processing.py — Core Generation Pipeline

The heart of image generation. Contains the base class `StableDiffusionProcessing` and its two subclasses `StableDiffusionProcessingTxt2Img` and `StableDiffusionProcessingImg2Img`.

The primary entry point is `process_images(p)`, which:
1. Validates parameters and loads models
2. Calls `process_images_inner(p)` inside the FIFO queue lock
3. Runs the sampler for the configured number of steps
4. Decodes latents via VAE
5. Applies face restoration and upscaling if configured
6. Saves images with metadata embedded in EXIF/PNG chunks
7. Returns a `Processed` object with images and generation info

Key classes:
- `StableDiffusionProcessing` — base with all generation parameters (prompt, negative_prompt, steps, cfg_scale, seed, width, height, sampler_name, etc.)
- `StableDiffusionProcessingTxt2Img` — adds high-res fix support (enable_hr, hr_upscaler, hr_scale, denoising_strength)
- `StableDiffusionProcessingImg2Img` — adds init_images, mask, resize_mode, inpainting parameters
- `Processed` — results container with images, seeds, info text, generation parameters

#### modules/sd_models.py — Model Management

Manages checkpoint discovery, loading, and switching.

- `CheckpointInfo` — metadata wrapper for discovered checkpoints (path, hash, model_name, config)
- `SdModelData` — singleton managing the currently loaded model
- `list_models()` — scans checkpoint directories, builds model list
- `load_model(checkpoint_info)` — loads weights, applies config, sends to device
- `reload_model_weights(sd_model, info)` — hot-swaps weights without full reinitialization

#### modules/sd_samplers*.py — Sampler System

A modular sampler architecture:

- `sd_samplers.py` — registry of all available samplers, `create_sampler()` factory
- `sd_samplers_kdiffusion.py` — wraps k-diffusion samplers (Euler, DPM++ 2M, DPM++ SDE, Heun, LMS, etc.) with the `KDiffusionSampler` class
- `sd_samplers_timesteps.py` — timestep-based samplers (DDIM, PLMS) via `CompVisSampler`
- `sd_samplers_common.py` — shared utilities: `SamplerData`, `Sampler` base, image storage during sampling
- `sd_samplers_lcm.py` — LCM (Latent Consistency Model) sampler support
- `sd_schedulers.py` — noise schedule definitions (uniform, karras, exponential, polyexponential, SGM uniform)

#### modules/sd_hijack.py — Model Hijacking

The hijack system modifies loaded models at runtime to inject:
- Optimized attention implementations (from `sd_hijack_optimizations.py`)
- Textual inversion embedding support (custom tokens mapped to learned vectors)
- Prompt weighting through modified CLIP forward passes

`StableDiffusionModelHijack` patches the model's attention layers, CLIP text encoder, and adds hooks for extra networks. This is reversed via `undo_hijack()` before model unloading.

#### modules/sd_hijack_optimizations.py — Attention Implementations

Contains the actual implementations of all attention optimization variants:
- `xformers_attention_forward()` — xformers memory-efficient attention
- `sdp_attention_forward()` — PyTorch scaled dot-product attention
- `sub_quad_attention_forward()` — sub-quadratic attention with configurable chunking
- `split_cross_attention_forward_invokeAI()` — InvokeAI's chunked attention
- `split_cross_attention_forward()` — Doggettx's split attention
- `split_cross_attention_forward_v1()` — original v1 implementation

#### modules/scripts.py — Script System

The extensibility backbone. Scripts are Python classes that inherit from `Script` and implement lifecycle hooks:

```python
class Script:
    def title(self) -> str                    # Display name
    def ui(self, is_img2img) -> list          # Gradio UI components
    def show(self, is_img2img) -> bool        # Visibility control
    def run(self, p, *args)                   # Main execution
    def before_process(self, p, *args)        # Pre-processing hook
    def process(self, p, *args)               # During processing
    def before_process_batch(self, p, *args)  # Pre-batch hook
    def process_batch(self, p, *args)         # Batch processing
    def postprocess(self, p, processed, *args)  # Post-processing
    def postprocess_batch(self, p, *args)     # Post-batch
    def postprocess_image(self, p, pp, *args) # Per-image post
    def describe(self) -> str                 # Description text
```

`ScriptRunner` discovers scripts from `scripts/` directories (both root and extension), instantiates them, and invokes the appropriate hooks during generation.

#### modules/script_callbacks.py — Callback System

Provides 30+ named callback hooks that extensions register into:

| Callback | Trigger |
|----------|---------|
| `on_app_started` | After Gradio app launches |
| `on_model_loaded` | After a checkpoint loads |
| `on_script_unloaded` | Before scripts reload |
| `on_before_image_saved` | Before image write |
| `on_image_saved` | After image write |
| `on_cfg_denoiser` | Each denoiser step |
| `on_before_component` | Before Gradio component creation |
| `on_after_component` | After Gradio component creation |
| `on_ui_tabs` | When building UI tabs |
| `on_ui_settings` | When building Settings tab |
| `on_ui_train_tabs` | When building training tabs |
| `on_extra_noise` | When applying extra noise |
| `on_before_ui` | Before UI construction |
| `on_infotext_pasted` | When generation info is pasted |
| `on_list_optimizers` | When listing attention optimizers |

#### modules/extra_networks.py — Extra Network System

Handles activation of LoRA, hypernetworks, and embeddings via prompt syntax:

```
<lora:model_name:weight>
<hypernet:model_name:weight>
```

The system parses these tags from the prompt, loads the referenced networks, and applies their weights to the active model before generation. After generation, the networks are deactivated.

#### modules/api/api.py — REST API

The `Api` class mounts 35+ endpoints onto Gradio's FastAPI app. Key implementation details:
- Generation endpoints (`txt2img`, `img2img`) use the same `processing.py` pipeline as the UI
- Images are serialized as base64-encoded strings in JSON responses
- The `encode_pil_to_base64()` / `decode_base64_to_image()` utilities handle image serialization
- Progress polling via `GET /sdapi/v1/progress` returns percentage, ETA, and optionally a live preview image

#### modules/call_queue.py — Generation Queue

Implements a FIFO (fair) lock that serializes all GPU-intensive operations. The `queue_lock` ensures only one generation runs at a time, preventing GPU OOM from concurrent requests. The lock is fair (FIFO ordering), so requests are processed in submission order rather than allowing starvation.

#### modules/prompt_parser.py — Prompt Parsing

Parses the extended prompt syntax using the `lark` grammar library:

- **Emphasis**: `(word:1.3)` or `(word)` (default 1.1) increases attention weight; `[word]` decreases (0.9)
- **Prompt scheduling**: `[from:to:0.5]` switches prompt at 50% of steps
- **Alternation**: `[cat|dog]` alternates between terms each step
- **BREAK**: Splits prompt into separate conditioning chunks

The parser produces a `ScheduledPromptConditioning` tree that the conditioning system evaluates at each denoising step.

#### modules/safe.py — Safe Unpickle

`RestrictedUnpickler` extends Python's `Unpickler` with a `find_class()` override that checks every class reference against `_safe_classes`. The `check_pt()` function additionally scans raw file bytes for dangerous patterns before any unpickling occurs.

### 8.3 REST API Reference

All endpoints are prefixed with `/sdapi/v1/` and require `--api` (or `--nowebui`) to be enabled.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/sdapi/v1/txt2img` | Text-to-image generation |
| POST | `/sdapi/v1/img2img` | Image-to-image generation |
| POST | `/sdapi/v1/extra-single-image` | Postprocess a single image (upscale, face restore) |
| POST | `/sdapi/v1/extra-batch-images` | Postprocess multiple images |
| POST | `/sdapi/v1/png-info` | Extract generation parameters from PNG metadata |
| GET | `/sdapi/v1/progress` | Poll generation progress (percent, ETA, preview) |
| POST | `/sdapi/v1/interrogate` | CLIP/BLIP interrogation (image to prompt) |
| POST | `/sdapi/v1/interrupt` | Interrupt current generation |
| POST | `/sdapi/v1/skip` | Skip to next step/image in batch |
| GET | `/sdapi/v1/options` | Get all current settings |
| POST | `/sdapi/v1/options` | Update settings (partial update) |
| GET | `/sdapi/v1/cmd-flags` | Get active command-line flags |
| GET | `/sdapi/v1/samplers` | List available samplers |
| GET | `/sdapi/v1/schedulers` | List available noise schedulers |
| GET | `/sdapi/v1/upscalers` | List available upscalers |
| GET | `/sdapi/v1/latent-upscale-modes` | List latent upscale modes |
| GET | `/sdapi/v1/sd-models` | List available SD checkpoints |
| GET | `/sdapi/v1/sd-vae` | List available VAE models |
| GET | `/sdapi/v1/hypernetworks` | List available hypernetworks |
| GET | `/sdapi/v1/face-restorers` | List face restoration models |
| GET | `/sdapi/v1/realesrgan-models` | List RealESRGAN models |
| GET | `/sdapi/v1/prompt-styles` | List saved prompt styles |
| GET | `/sdapi/v1/embeddings` | List textual inversion embeddings |
| POST | `/sdapi/v1/refresh-embeddings` | Rescan embeddings directory |
| POST | `/sdapi/v1/refresh-checkpoints` | Rescan checkpoints directory |
| POST | `/sdapi/v1/refresh-vae` | Rescan VAE directory |
| POST | `/sdapi/v1/create/embedding` | Create a new textual inversion embedding |
| POST | `/sdapi/v1/create/hypernetwork` | Create a new hypernetwork |
| POST | `/sdapi/v1/train/embedding` | Start textual inversion training |
| POST | `/sdapi/v1/train/hypernetwork` | Start hypernetwork training |
| GET | `/sdapi/v1/memory` | GPU/CPU memory usage info |
| POST | `/sdapi/v1/unload-checkpoint` | Unload current model from VRAM |
| POST | `/sdapi/v1/reload-checkpoint` | Reload model to VRAM |
| GET | `/sdapi/v1/scripts` | List available scripts (txt2img + img2img) |
| GET | `/sdapi/v1/script-info` | Detailed script info with argument definitions |
| GET | `/sdapi/v1/extensions` | List installed extensions |
| POST | `/sdapi/v1/server-kill` | Kill server process (requires `--api-server-stop`) |
| POST | `/sdapi/v1/server-restart` | Restart server (requires `--api-server-stop`) |
| POST | `/sdapi/v1/server-stop` | Stop server gracefully (requires `--api-server-stop`) |

Additionally, Gradio auto-generates:
- `GET /docs` — Swagger UI (interactive API documentation)
- `GET /redoc` — ReDoc API documentation

**Example: Text-to-image via API**

```python
import requests
import base64
from PIL import Image
from io import BytesIO

url = "http://127.0.0.1:7860/sdapi/v1/txt2img"
payload = {
    "prompt": "a photograph of an astronaut riding a horse",
    "negative_prompt": "blurry, low quality",
    "steps": 20,
    "cfg_scale": 7.0,
    "width": 512,
    "height": 512,
    "sampler_name": "Euler a",
    "seed": -1
}

response = requests.post(url, json=payload)
result = response.json()

# Decode the first image
image_data = base64.b64decode(result["images"][0])
image = Image.open(BytesIO(image_data))
image.save("output.png")
```

**Example: Switch model via API**

```python
# Get current options
options = requests.get("http://127.0.0.1:7860/sdapi/v1/options").json()

# Switch checkpoint
requests.post("http://127.0.0.1:7860/sdapi/v1/options", json={
    "sd_model_checkpoint": "v1-5-pruned-emaonly.safetensors"
})
```

### 8.4 Extension System Architecture

#### Script-Based Extensions

The simplest extension type. Place a Python file in `extensions/your-extension/scripts/` that defines a class inheriting from `modules.scripts.Script`. The `ScriptRunner` discovers and loads it automatically.

The script lifecycle during generation:

```
ScriptRunner.run()
  → before_process()      for each script
  → process()             for each script
  → before_process_batch() for each script in batch
  → process_batch()       for each script in batch
  [generation happens]
  → postprocess_batch()   for each script in batch
  → postprocess_image()   for each image
  → postprocess()         for each script
```

#### Callback-Based Extensions

Extensions register functions via `script_callbacks.py`:

```python
from modules import script_callbacks

def on_model_loaded(sd_model):
    print(f"Model loaded: {sd_model.sd_checkpoint_info.title}")

script_callbacks.on_model_loaded(on_model_loaded)
```

#### Extra Network Extensions

For adding new network types (like LoRA), extensions implement `ExtraNetwork` subclass and register via `extra_networks.register_extra_network()`.

#### Extension Metadata

Extensions can include a `metadata.ini` or `preload.py` for:
- Declaring dependencies on other extensions
- Running code before the main application initializes
- Specifying compatible WebUI versions

#### Extension Discovery Order

1. `extensions-builtin/` directories (alphabetical)
2. `extensions/` directories (alphabetical)
3. Within each extension: `preload.py` → `install.py` (first run) → `scripts/*.py`

### 8.5 Code Patterns

#### Monkey Patching ("Hijacking")

The dominant code pattern throughout the codebase. Rather than forking upstream libraries, the WebUI patches their methods at runtime:

```python
# Example from sd_hijack.py
ldm.modules.attention.CrossAttention.forward = sd_hijack_optimizations.xformers_attention_forward
```

This approach enables:
- Injecting optimized attention without modifying k-diffusion or ldm source
- Adding embedding support to CLIP without forking transformers
- Swapping implementations based on runtime flags

The pattern is used extensively in `sd_hijack.py`, `sd_hijack_clip.py`, `sd_hijack_unet.py`, and `sd_disable_initialization.py`.

#### FIFO Queue Lock

All GPU-intensive operations go through the `queue_lock` in `call_queue.py`:

```python
from modules.call_queue import queue_lock

with queue_lock:
    # Only one generation at a time
    result = process_images(p)
```

The lock uses `FIFOLock` (from `fifo_lock.py`) to ensure fair ordering — requests are served in arrival order, preventing starvation of long-queued requests.

#### Gradio Component Wrapping

Custom UI components extend Gradio's built-in components via `FormComponent` subclasses in `ui_components.py`:

- `FormRow`, `FormColumn`, `FormGroup` — layout with CSS classes
- `ToolButton` — small icon buttons
- `InputAccordion` — collapsible section with checkbox header
- `ResizeHandleRow` — resizable column layout
- `DropdownMulti`, `DropdownEditable` — enhanced dropdowns

These wrappers add consistent styling, event handling, and metadata tracking.

#### Config States for Rollback

The system can snapshot the current configuration (`config.json` + extension states) and restore it later. This is used for:
- Rolling back after a bad settings change
- Switching between configuration profiles
- Extension debugging (disable all, test one at a time)

#### Safe Unpickle Pattern

Every `torch.load()` call goes through the patched path:

```python
# safe.py patches torch.load to use RestrictedUnpickler
torch.load = safe.unsafe_torch_load  # original
torch.load = safe.load               # patched (default)
```

The `RestrictedUnpickler.find_class()` checks every class against the allowlist before instantiation.

### 8.6 Error Messages Reference

| Error Message | Source | Cause | Fix |
|--------------|--------|-------|-----|
| `Torch is not able to use GPU` | `launch_utils.py` | CUDA not available or wrong PyTorch build | Install CUDA-enabled PyTorch; use `--skip-torch-cuda-test` for non-CUDA platforms |
| `Checkpoint not found` | `sd_models.py` | Specified `--ckpt` file doesn't exist | Verify path; place `.safetensors`/`.ckpt` in `models/Stable-diffusion/` |
| `OutOfMemoryError: CUDA out of memory` | PyTorch | VRAM exhausted during generation | Use `--medvram`, `--lowvram`, reduce image dimensions, or use `--xformers` |
| `NansException: A tensor with all NaNs was produced` | `devices.py` | Numerical instability in generation | Use `--no-half` or `--no-half-vae`; try different seed |
| `RuntimeError: expected scalar type Half but found Float` | PyTorch | dtype mismatch between model components | Use `--no-half` or `--upcast-sampling`; may indicate incompatible extension |
| `connection refused` / `Empty reply from server` | Gradio/Uvicorn | Server not ready or crashed during startup | Check logs for model load errors; increase `--timeout-keep-alive` |
| `ModuleNotFoundError: No module named 'xformers'` | Python | xformers not installed | Run with `--reinstall-xformers` or remove `--xformers` flag |
| `Error running install.py for extension` | `launch_utils.py` | Extension install script failed | Check extension compatibility; run with `--disable-extra-extensions` to isolate |
| `pickle.UnpicklingError: Unsafe global` | `safe.py` | Model file contains blocked class reference | File may be malicious; use `.safetensors` format instead |
| `AssertionError: extension access disabled` | `ui_extensions.py` | Extensions tab used without proper flag | Add `--enable-insecure-extension-access` |
| `ValueError: could not convert string to float` | `prompt_parser.py` | Malformed prompt emphasis syntax | Check bracket/parenthesis matching in prompt |
| `RuntimeError: CUDA error: device-side assert triggered` | PyTorch/CUDA | Various — often negative dimensions or invalid indices | Restart; check for incompatible model/VAE combination |
| `FileNotFoundError: [Errno 2] No such file or directory: 'git'` | `launch_utils.py` | Git not installed or not in PATH | Install git and ensure it's on the system PATH |
| `httpx.ConnectError` | `launch_utils.py` | Network error during dependency download | Check internet connection; set `INDEX_URL` for alternative pip mirror |
| `Black images / green images` | `sd_vae.py` | VAE precision issue | Add `--no-half-vae`; try a different VAE |

> [!NOTE]
> The `NansException` error most commonly occurs with certain model/VAE combinations in float16 mode. Adding `--no-half-vae` resolves the majority of cases without the full performance penalty of `--no-half`.

> [!TIP]
> Run `python launch.py --dump-sysinfo` to generate a comprehensive JSON report of your environment (Python version, torch version, GPU info, installed packages, extensions). This is the most useful artifact to include when filing bug reports.

### 8.7 Testing

The test suite lives in the `test/` directory and uses pytest.

**Test files:**
- `test/test_txt2img.py` — Text-to-image generation tests
- `test/test_img2img.py` — Image-to-image generation tests
- `test/test_extras.py` — Postprocessing/extras tests
- `test/test_face_restorers.py` — Face restoration tests
- `test/test_torch_utils.py` — PyTorch utility tests
- `test/test_utils.py` — General utility tests

**Running tests:**

```bash
# Start the server in test mode
python launch.py --test-server --api --nowebui

# In another terminal, run tests
pip install -r requirements-test.txt
pytest test/ -v
```

The `--test-server` flag configures the server with settings suitable for automated testing (deterministic seeds, predictable outputs).

> [!TIP]
> Tests require a running server instance with `--api` enabled. The test suite makes HTTP requests to the API endpoints rather than importing modules directly, making these integration tests rather than unit tests.

### 8.8 Contributing

**Python**: 3.10+ required. The codebase does not use type hints consistently. A `.pylintrc` configuration is provided for linting.

**JavaScript**: The frontend uses vanilla JavaScript (no framework). ESLint is configured with `eslint:recommended` rules. Frontend code lives in `javascript/` and `script.js`.

**Code style**: No formal formatter is enforced. Follow existing patterns in the module you're modifying.

**Git**: A `.git-blame-ignore-revs` file is provided to skip formatting-only commits in `git blame` output.

**Extension development**: The recommended approach for adding features. Extensions are isolated, independently versioned, and don't require modifying the core codebase. See Section 8.4 for the extension architecture.

---

## 9. Integration Points

### Gradio Public Sharing

The `--share` flag creates a public URL via Gradio's share server:

```bash
./webui.sh --share
# Output: Running on public URL: https://xxxxx.gradio.live
```

Share links expire after 72 hours. They tunnel traffic through Gradio's servers, so no port forwarding or DNS configuration is needed.

### ngrok Tunneling

For persistent public URLs:

```bash
export COMMANDLINE_ARGS="--ngrok YOUR_AUTH_TOKEN"
```

The `--ngrok-options` flag accepts a JSON object for additional configuration (custom domain, region, IP restrictions).

### REST API for Automation

The API (Section 8.3) enables full automation of the generation pipeline. Common integration patterns:

- **Discord/Telegram bots**: Poll `/sdapi/v1/progress`, submit via `/sdapi/v1/txt2img`
- **Batch processing**: Script that iterates prompts and collects results
- **Pipeline integration**: Chain with upscaling, face restoration, or custom postprocessing
- **Model management**: Switch models between batches via `POST /sdapi/v1/options`

### Extension Ecosystem

The WebUI has a large third-party extension ecosystem. Extensions are installed via git URL through the Extensions tab or manually by cloning into `extensions/`. The official extension index is fetched from `WEBUI_EXTENSIONS_INDEX`.

Popular extension categories:
- ControlNet (pose/depth/edge-guided generation)
- Regional prompting (different prompts for different image regions)
- Animation (AnimateDiff, Deforum)
- Upscaling (Tiled VAE, Ultimate SD Upscale)
- Training (Dreambooth, dataset tools)
- UI improvements (tag autocomplete, image browser)

### HuggingFace Model Hub

The WebUI downloads models from HuggingFace using the `HF_ENDPOINT` environment variable (defaults to `https://huggingface.co`). This includes:
- Initial Stable Diffusion model download (if no model present)
- CLIP model weights
- Various auxiliary models

For environments with restricted internet access, set `HF_ENDPOINT` to a local mirror.

### Civitai Model Compatibility

The WebUI natively supports model files downloaded from Civitai. Checkpoints (`.safetensors`, `.ckpt`), LoRA files, textual inversion embeddings, hypernetworks, and VAE models from Civitai are placed in their respective `models/` subdirectories and are discovered automatically.

> [!NOTE]
> When downloading `.ckpt` files from any source (including Civitai), the safe unpickler will validate the file on first load. Prefer `.safetensors` format when available, as it is inherently safe and loads faster.

For usage instructions, installation walkthrough, and feature documentation, see the companion [User Guide](/guides/AUTOMATIC1111/stable-diffusion-webui/user-guide/).

---

_Generated May 2026 from AUTOMATIC1111/stable-diffusion-webui at 82a973c. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._