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

Technology Stack

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

Software Requirements

Supported GPU Platforms

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

Model & Checkpoint Flags

Performance & Memory Flags

Network & Server Flags

Authentication Flags

UI Flags

API Flags

Path Flags

Extension Flags

Safety Flags

Deprecated / No-Op Flags

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

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.

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:

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:

./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:

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:

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

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

For persistent tunneling via ngrok:

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:

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

Example nginx configuration:

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):

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):

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

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:

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.

# 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.

--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:

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:

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.

Additionally, Gradio auto-generates:

• GET /docs — Swagger UI (interactive API documentation)
• GET /redoc — ReDoc API documentation

Example: Text-to-image via API

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

# 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:

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:

# 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:

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:

# 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

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:

# 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:

./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:

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.