# Stable Diffusion WebUI — User Guide

## 1. Quick Start

Stable Diffusion WebUI (commonly called "A1111") is a browser-based interface for running Stable Diffusion image generation models locally on your own hardware. Built on Gradio, it provides a full-featured GUI for text-to-image, image-to-image, inpainting, upscaling, and dozens of other image generation workflows — all without cloud dependencies or subscriptions.

### Key Features

- **Text-to-image generation** with advanced prompt syntax (emphasis, scheduling, alternation)
- **Image-to-image** with inpainting, outpainting, and InstructPix2Pix support
- **Multiple model architectures**: SD 1.x, SD 2.x, SDXL, SD3, Alt-Diffusion
- **Extra networks**: LoRA, LyCORIS, textual inversion embeddings, hypernetworks
- **Upscaling**: ESRGAN, RealESRGAN, SwinIR, ScuNET, DAT, HAT, LDSR, and more
- **Face restoration**: CodeFormer and GFPGAN
- **X/Y/Z plot** for systematic parameter comparison
- **Extensions system** for community-built add-ons
- **REST API** for programmatic access and automation

### Prerequisites

- **GPU**: NVIDIA GPU with 4 GB+ VRAM (6 GB+ recommended); AMD GPUs supported on Linux
- **Python**: 3.10.x (3.10.6 recommended; 3.12+ may cause issues)
- **Git**: installed and on PATH
- **Disk**: ~10 GB for installation + models (each checkpoint is 2–7 GB)

### Quickest Install (Windows)

```batch
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
webui-user.bat
```

The launcher automatically creates a Python virtual environment, installs dependencies, and opens the UI at `http://127.0.0.1:7860`.

> [!TIP]
> Place your model checkpoint files (`.safetensors` or `.ckpt`) in the `models/Stable-diffusion/` folder before launching. The UI will detect them on startup and let you select from a dropdown.

### First Image

1. Select a model from the **Stable Diffusion checkpoint** dropdown at the top
2. Type a prompt: `a photo of a mountain landscape at sunset, dramatic lighting, 4k`
3. Click **Generate** (or press **Ctrl+Enter**)
4. Your image appears in the output gallery within seconds

### What to Try Next

- [Section 4.1](#41-text-to-image-txt2img) — master prompt syntax and sampling parameters
- [Section 4.2](#42-image-to-image-img2img) — transform existing images
- [Section 4.5](#45-using-extra-networks) — add LoRAs for styles and characters
- [Section 5](#5-common-tasks) — step-by-step recipes for popular workflows

---

## 2. Installation

### System Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| GPU | NVIDIA 4 GB VRAM | NVIDIA 8+ GB VRAM |
| RAM | 8 GB | 16 GB |
| Disk | 10 GB (+ models) | 50 GB SSD |
| Python | 3.10.x | 3.10.6 |
| OS | Windows 10, Linux, macOS 12+ | Windows 10/11, Ubuntu 22.04+ |
| Git | 2.x | Latest |

> [!IMPORTANT]
> Python 3.10.x is strongly recommended. Versions 3.12 and above may fail during dependency installation due to breaking changes in `setuptools` and `distutils`. If you see `Cannot import setuptools.build_meta`, downgrade to Python 3.10.6.

### Platform-Specific Instructions

=== "Windows"

1. Install [Python 3.10.6](https://www.python.org/downloads/release/python-3106/) — check **"Add Python to PATH"** during install
2. Install [Git for Windows](https://git-scm.com/download/win)
3. Clone and launch:

```batch
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
webui-user.bat
```

The batch file creates a `venv`, installs PyTorch with CUDA support, installs all Python dependencies, and starts the server.

=== "Linux"

1. Install prerequisites:

```bash
# Ubuntu/Debian
sudo apt install wget git python3 python3-venv libgl1 libglib2.0-0

# Arch
sudo pacman -S wget git python3
```

2. Clone and launch:

```bash
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
./webui.sh
```

The shell script sources `webui-user.sh` for configuration, creates a venv, installs dependencies, and starts the server.

=== "macOS"

1. Install [Homebrew](https://brew.sh), then:

```bash
brew install cmake protobuf rust python@3.10 git wget
```

2. Clone and launch:

```bash
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
./webui.sh
```

On macOS, the launcher automatically sources `webui-macos-env.sh`, which sets `--skip-torch-cuda-test`, `--upcast-sampling`, `--no-half-vae`, and `--use-cpu interrogate` for Apple Silicon compatibility.

=== "Docker"

The repository does not include an official Dockerfile. Community-maintained Docker images are available on Docker Hub and GitHub Container Registry.

> [!WARNING]
> Always verify the source of third-party Docker images before running them. Prefer images with published Dockerfiles you can audit.

Check the project wiki for community Docker setups that bundle NVIDIA Container Toolkit support.

### Environment Variables

Customize the installation and launch behavior by setting these variables in `webui-user.bat` (Windows) or `webui-user.sh` (Linux/macOS):

| Variable | Default | Purpose |
|----------|---------|---------|
| `COMMANDLINE_ARGS` | *(empty)* | CLI flags passed to `launch.py` |
| `TORCH_COMMAND` | *(auto-detected)* | Custom PyTorch install command |
| `TORCH_INDEX_URL` | `https://download.pytorch.org/whl/cu121` | PyTorch wheel index URL |
| `REQS_FILE` | `requirements_versions.txt` | Requirements file to install from |
| `XFORMERS_PACKAGE` | *(auto)* | Specific xformers version |
| `GIT` | `git` | Path to git executable |
| `SD_WEBUI_LOG_LEVEL` | *(default)* | Python log level |
| `SD_WEBUI_RICH_LOG` | *(off)* | Enable rich formatted logging |
| `GRADIO_TEMP_DIR` | *(system temp)* | Temp directory for Gradio files |
| `WEBUI_EXTENSIONS_INDEX` | *(built-in)* | Custom extensions index URL |
| `HF_ENDPOINT` | `https://huggingface.co` | HuggingFace endpoint override |

### Post-Install Verification

After the first launch completes, verify:

1. The console shows `Running on local URL: http://127.0.0.1:7860`
2. Open `http://127.0.0.1:7860` in your browser
3. The checkpoint dropdown at the top lists your model files
4. Generate a test image with a simple prompt

### Customizing Launch (webui-user Files)

**Windows** — edit `webui-user.bat`:

```batch
@echo off
set COMMANDLINE_ARGS=--xformers --autolaunch
set TORCH_COMMAND=pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
```

**Linux/macOS** — edit `webui-user.sh`:

```bash
export COMMANDLINE_ARGS="--xformers --autolaunch"
export TORCH_COMMAND="pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121"
```

---

## 3. Configuration

### UI Settings Tab

The **Settings** tab in the web interface exposes hundreds of configurable options organized into sections. Changes take effect after clicking **Apply settings** (some require **Reload UI**). Settings are persisted to `config.json` in the webui root.

Key user-facing settings categories:

- **Saving images**: output directory, filename patterns, image format (PNG/JPEG/WEBP), quality, metadata embedding
- **Saving paths**: per-feature output directories (txt2img, img2img, extras, grids)
- **Face restoration**: default model, CodeFormer fidelity weight
- **Upscaling**: default upscaler for hires fix, upscaler order in the UI
- **Stable Diffusion**: checkpoint, VAE, clip skip, emphasis mode, enable quantization
- **Sampler parameters**: default sampler, eta, s_churn, s_noise
- **UI**: theme, quicksettings list, gallery height

### Command-Line Flags

Pass flags via `COMMANDLINE_ARGS` in your `webui-user` file or directly on the command line.

#### GPU & Memory

| Flag | Effect |
|------|--------|
| `--medvram` | Split model into three parts to reduce VRAM usage (~4 GB) |
| `--lowvram` | Aggressive VRAM optimization for GPUs with 2–4 GB |
| `--no-half` | Use full float32 precision (fixes NaN on some GPUs) |
| `--no-half-vae` | Use float32 for VAE only (fixes black images) |
| `--xformers` | Enable xformers memory-efficient attention (recommended for NVIDIA) |
| `--opt-sdp-attention` | Use PyTorch 2.0 scaled dot product attention |
| `--opt-sdp-no-mem-attention` | SDP attention without memory-efficient mode |
| `--opt-sub-quad-attention` | Sub-quadratic attention (lower VRAM, slower) |
| `--upcast-sampling` | Upcast sampling for better precision (needed on macOS) |
| `--skip-torch-cuda-test` | Skip CUDA availability check (for CPU/macOS) |
| `--use-cpu` | Force specific modules to CPU (e.g., `--use-cpu interrogate`) |

#### Network

| Flag | Effect |
|------|--------|
| `--listen` | Listen on `0.0.0.0` instead of `127.0.0.1` (LAN access) |
| `--port PORT` | Set the listening port (default: 7860) |
| `--share` | Create a Gradio public URL (temporary tunnel) |
| `--ngrok TOKEN` | Use ngrok for public access with auth token |
| `--gradio-auth USER:PASS` | Require login credentials for the UI |

#### UI

| Flag | Effect |
|------|--------|
| `--theme` | Set Gradio theme (`dark` or `light`) |
| `--autolaunch` | Open browser automatically on start |

#### Paths

| Flag | Effect |
|------|--------|
| `--ckpt-dir PATH` | Custom directory for model checkpoints |
| `--vae-dir PATH` | Custom directory for VAE models |
| `--embeddings-dir PATH` | Custom directory for textual inversion embeddings |
| `--lora-dir PATH` | Custom directory for LoRA files |
| `--data-dir PATH` | Base directory for all data |
| `--styles-file PATH` | Path to styles CSV file(s) (supports glob patterns) |

#### API & Misc

| Flag | Effect |
|------|--------|
| `--api` | Enable the REST API alongside the web UI |
| `--api-auth USER:PASS` | Set API authentication credentials |
| `--nowebui` | Run API-only without the Gradio UI |
| `--cors-allow-origins URL` | Allow CORS from specified origins |
| `--freeze-settings` | Prevent settings from being modified through the UI |
| `--disable-safe-unpickle` | Disable safety check for pickle files (use with caution) |

For the complete flag reference with all 129 flags, see the Admin Guide.

### Styles Files

The `--styles-file` flag specifies one or more CSV files containing saved prompt styles. By default, this is `styles.csv` in the webui root. You can specify multiple files using glob patterns (e.g., `--styles-file "styles/*.csv"`).

---

## 4. Core Usage

### 4.1 Text-to-Image (txt2img)

The txt2img tab is the primary interface for generating images from text descriptions.

#### Prompt Syntax

Prompts support several special syntax features:

**Emphasis** — adjust the weight of specific terms:

```
(word)           — increase attention by 1.1x
((word))         — increase attention by 1.21x (1.1 * 1.1)
(word:1.5)       — increase attention by 1.5x
[word]           — decrease attention by 1.1x (multiply by 1/1.1)
```

**Prompt scheduling** — change prompts during generation:

```
[from:to:0.5]    — switch from "from" to "to" at 50% of steps
[from:to:10]     — switch at step 10
[to:0.5]         — add "to" starting at 50% of steps
[from::0.5]      — remove "from" after 50% of steps
```

**Alternating** — alternate between terms each step:

```
[cat|dog]        — alternate between cat and dog each step
[cat|dog|bird]   — cycle through three terms
```

> [!NOTE]
> Prompt weights stack multiplicatively. `((word))` is equivalent to `(word:1.21)`. Avoid extreme weights above 2.0 or below 0.3, as they tend to produce artifacts rather than meaningful emphasis changes.

#### Negative Prompts

The negative prompt field tells the model what to avoid. Common negative prompt terms:

```
blurry, low quality, deformed, ugly, extra limbs, watermark, text, signature
```

Negative prompts use the same syntax as positive prompts, including emphasis and scheduling.

#### Sampling Parameters

| Parameter | Range | Purpose |
|-----------|-------|---------|
| **Sampler** | 27 options | Algorithm for denoising (see sampler list below) |
| **Steps** | 1–150 | Number of denoising iterations; 20–30 is typical |
| **CFG Scale** | 1–30 | How closely to follow the prompt; 7–12 is typical |
| **Seed** | -1 or fixed | Random seed; -1 for random, fixed for reproducibility |
| **Width/Height** | 64–2048 | Output resolution (in 8-pixel increments) |

#### Batch Controls

- **Batch count**: how many batches to run sequentially
- **Batch size**: how many images to generate in parallel per batch (limited by VRAM)

#### Hires Fix

Hires fix generates at a lower resolution first, then upscales and re-renders at full resolution. This avoids the composition problems that occur when generating directly at high resolutions with SD 1.x/2.x models.

1. Enable the **Hires. fix** checkbox
2. Choose an **Upscaler** (Latent, ESRGAN, etc.)
3. Set **Hires steps** (0 = same as main steps)
4. Set **Denoising strength** (0.5–0.7 typical)
5. Set target resolution with **Upscale by** or explicit dimensions

> [!TIP]
> For SD 1.5 models, generate at 512x512 with Hires fix upscaling to 1024x1024. This produces much better results than generating directly at 1024x1024, which often creates duplicated subjects or distorted anatomy.

### 4.2 Image-to-Image (img2img)

The img2img tab transforms an existing image guided by a text prompt.

#### Basic Workflow

1. Upload or drag an image to the input area
2. Write a prompt describing the desired output
3. Set **Denoising strength** (0.0 = no change, 1.0 = completely new image; 0.4–0.75 typical)
4. Click Generate

#### Resize Modes

| Mode | Behavior |
|------|----------|
| **Just resize** | Stretch to target dimensions |
| **Crop and resize** | Crop to aspect ratio, then resize |
| **Resize and fill** | Fit within dimensions, fill empty space |
| **Just resize (latent upscale)** | Resize in latent space |

#### Inpainting

Inpainting lets you selectively regenerate parts of an image:

1. Switch to the **Inpaint** sub-tab
2. Upload an image
3. Paint over the area you want to regenerate (white = regenerate, black = keep)
4. Write a prompt for what should appear in the masked area
5. Configure fill settings:
   - **Fill**: fill masked area with blurred surroundings
   - **Original**: keep original content as starting point
   - **Latent noise**: fill with random noise
   - **Latent nothing**: fill with zero latent

**Soft inpainting** (available via the built-in extension) provides smoother blending at mask boundaries by using a gradient transition instead of a hard edge.

#### InstructPix2Pix

When using an InstructPix2Pix model (`instruct-pix2pix.yaml` config), you can give editing instructions as prompts (e.g., "make it winter", "change the color to red") and the model applies those edits while preserving the overall image structure.

### 4.3 Upscaling & Extras

The **Extras** tab provides standalone upscaling and post-processing without regeneration.

#### Available Upscalers

| Upscaler | Best For |
|----------|----------|
| **ESRGAN_4x** | General purpose |
| **RealESRGAN** (multiple variants) | Photos, realistic content |
| **SwinIR** | High quality, slower |
| **ScuNET** | Denoising + upscaling |
| **DAT** | State-of-the-art quality |
| **HAT** | High-accuracy texture recovery |
| **LDSR** | Highest quality, very slow |
| **Lanczos** | Fast, traditional algorithm |
| **Nearest** | Pixel art (no interpolation) |

#### Usage

1. Go to the **Extras** tab
2. Upload a single image or use the **Batch Process** / **Batch from Directory** sub-tabs
3. Select an upscaler from the **Upscaler 1** dropdown
4. Set the **Resize** factor (e.g., 2x, 4x) or explicit target dimensions
5. Optionally set **Upscaler 2** with a visibility blend for combining two upscalers
6. Click **Generate**

### 4.4 Face Restoration

Two face restoration models are available as post-processors:

**CodeFormer** — the recommended option, with an adjustable **weight** parameter:
- Weight 0 = maximum restoration (sharper faces, may alter features)
- Weight 1 = maximum fidelity (preserves original, less correction)
- Weight 0.5 is a good starting point

**GFPGAN** — an older alternative, no weight parameter.

Face restoration can be applied:
- Automatically during generation (enable in Settings → Face restoration)
- As a post-processor in the Extras tab
- Via the built-in scripts (`postprocessing_codeformer.py`, `postprocessing_gfpgan.py`)

### 4.5 Using Extra Networks

Extra networks modify the generation process without changing the base model. Access them via the card icon button below the Generate button.

#### LoRA / LyCORIS

LoRA (Low-Rank Adaptation) and LyCORIS files add trained concepts — characters, styles, objects — on top of a base model.

**Setup**: Place `.safetensors` files in `models/Lora/`.

**Usage**: Click the LoRA card in the Extra Networks panel, or type directly in the prompt:

```
<lora:filename:weight>
```

- `filename` — the LoRA file name without extension
- `weight` — strength from 0.0 to 1.0+ (0.7–1.0 typical)

Example:

```
a portrait of a woman, studio lighting <lora:add_detail:0.8>
```

Multiple LoRAs can be combined:

```
landscape photo <lora:add_detail:0.6> <lora:more_lighting:0.4>
```

> [!NOTE]
> LoRA compatibility depends on the base model. A LoRA trained on SD 1.5 will not work with SDXL checkpoints and vice versa. Check the LoRA's documentation for the intended base model.

#### Textual Inversion Embeddings

Embeddings are small files that encode a learned concept as a prompt token.

**Setup**: Place `.pt` or `.safetensors` files in `embeddings/`.

**Usage**: Use the embedding's filename directly in your prompt or negative prompt. The Extra Networks panel shows available embeddings with preview thumbnails.

#### Hypernetworks

Hypernetworks modify the cross-attention layers. Place files in `models/hypernetworks/` and select from the Settings tab or Extra Networks panel.

### 4.6 Prompt Styles

Styles let you save and reuse prompt/negative-prompt combinations.

#### Saving a Style

1. Write your prompt and negative prompt
2. Click the save style button (floppy disk icon near the prompt fields)
3. Name the style

#### Applying a Style

Select one or more styles from the dropdown below the prompt fields. The style's prompt and negative prompt are appended to your current inputs.

#### Template Syntax

Styles support a `{prompt}` placeholder. If a style's prompt is:

```
{prompt}, masterpiece, best quality, highly detailed
```

Then your typed prompt replaces `{prompt}`, and the rest is appended.

### 4.7 Image Interrogation (CLIP / DeepDanbooru)

The **Interrogate** buttons on the img2img tab reverse-engineer a text prompt from an uploaded image.

- **CLIP Interrogate** (the "clipboard" button) — produces a natural-language description
- **DeepDanbooru** — produces anime/booru-style tags

Upload an image to img2img, then click the interrogate button. The generated prompt appears in the prompt field, ready for editing or use.

### 4.8 Extensions

Extensions add features without modifying the core codebase.

#### Installing from URL

1. Go to **Extensions** → **Install from URL**
2. Paste the git repository URL
3. Click **Install**
4. Go to **Installed** tab and click **Apply and restart UI**

#### Installing from Index

1. Go to **Extensions** → **Available**
2. Click **Load from** to fetch the extension index
3. Browse or search for extensions
4. Click **Install** on the desired extension

#### Managing Extensions

- **Enable/Disable**: toggle checkboxes on the **Installed** tab
- **Update**: click **Check for updates** then **Apply and restart UI**
- **Remove**: delete the extension folder from `extensions/`

#### Built-in Extensions

These ship with the webui and can be enabled/disabled:

| Extension | Purpose |
|-----------|---------|
| Canvas Zoom and Pan | Zoom/pan controls on img2img canvas |
| Prompt Bracket Checker | Warns about unmatched parentheses/brackets |
| Soft Inpainting | Smooth mask blending for inpainting |
| Extra Options Section | Additional UI options in the interface |
| SwinIR | SwinIR upscaler support |
| LDSR | LDSR upscaler support |
| ScuNET | ScuNET upscaler support |
| Lora | LoRA/LyCORIS network support |
| Mobile UI | Responsive layout for mobile browsers |
| Postprocessing for Training | Auto-crop, caption, flip, focal crop, split oversized |
| HyperTile | HyperTile optimization for faster generation |

> [!IMPORTANT]
> Extensions run arbitrary code on your system. Only install extensions from sources you trust. Review an extension's repository and community feedback before installing.

---

## 5. Common Tasks

### 5.1 Generate Your First Image

1. Launch the webui and navigate to `http://127.0.0.1:7860`
2. Select a checkpoint from the top dropdown (e.g., `v1-5-pruned.safetensors`)
3. In the prompt field, type: `a fluffy orange cat sitting on a windowsill, sunlight, soft focus`
4. Set Steps to `25`, CFG Scale to `7`, Size to `512x512`
5. Click **Generate** or press **Ctrl+Enter**
6. The output appears in the gallery on the right; click to view full-size

### 5.2 Use LoRA for Style or Character

1. Download a LoRA `.safetensors` file and place it in `models/Lora/`
2. Click the **Extra Networks** card button (below Generate)
3. Navigate to the **Lora** tab
4. Click the LoRA card to insert it into your prompt
5. Adjust the weight: `<lora:my_lora:0.8>`
6. Add your subject prompt before the LoRA tag
7. Generate

### 5.3 Upscale a Generated Image

1. Generate an image or go to the **Extras** tab
2. Upload the image (or send it from txt2img using the "Send to Extras" button)
3. Select **Upscaler 1**: `RealESRGAN_x4plus` (good general choice)
4. Set **Resize** to `2` (doubles dimensions)
5. Click **Generate**

### 5.4 Fix Faces in a Photo

1. Go to **Extras** tab
2. Upload the image with faces to fix
3. Enable **CodeFormer** under face restoration
4. Set **CodeFormer weight** to `0.5` (balance between restoration and fidelity)
5. Click **Generate**

### 5.5 Inpaint Part of an Image

1. Go to **img2img** → **Inpaint** sub-tab
2. Upload the image
3. Use the brush to paint over the area to regenerate
4. In the prompt, describe what should appear: `a red rose`
5. Set **Denoising strength** to `0.75`
6. Set **Masked content** to `fill`
7. Click **Generate**

### 5.6 Create Variations with Seed

1. Generate an image you like
2. Note the **Seed** value shown below the output image
3. Lock the seed by clicking the recycle icon (or enter it manually)
4. Make small prompt or parameter changes
5. Generate again — the composition stays similar while details change

For slight variations, use **Variation seed** with a small **Variation strength** (0.05–0.15).

### 5.7 Use X/Y/Z Plot for Parameter Comparison

1. In txt2img or img2img, open the **Script** dropdown at the bottom
2. Select **X/Y/Z plot**
3. Choose axis types (e.g., X = `Sampler`, Y = `Steps`, Z = `CFG Scale`)
4. Enter values:
   - Sampler: `Euler a, DPM++ 2M Karras, DDIM`
   - Steps: `10, 20, 30, 50`
   - CFG: `5, 7, 10`
5. Click **Generate** — produces a grid comparing every combination

> [!TIP]
> X/Y/Z plots are the fastest way to find optimal parameters for a new model or LoRA. Start with a sampler comparison, then narrow down steps and CFG scale.

### 5.8 Run the API Alongside the Web UI

1. Add `--api` to your `COMMANDLINE_ARGS`:

```bash
export COMMANDLINE_ARGS="--api"
```

2. Launch the webui normally
3. Access the API docs at `http://127.0.0.1:7860/docs` (Swagger UI)
4. Make requests programmatically:

```python
import requests
import base64

payload = {
    "prompt": "a beautiful sunset over mountains",
    "steps": 25,
    "width": 512,
    "height": 512
}

response = requests.post("http://127.0.0.1:7860/sdapi/v1/txt2img", json=payload)
image_data = response.json()["images"][0]

with open("output.png", "wb") as f:
    f.write(base64.b64decode(image_data))
```

### 5.9 Generate from a List of Prompts

1. Create a text file with one prompt per line:

```text
a red sports car on a mountain road
a blue sailboat on calm waters
a green forest with morning fog
```

2. In txt2img, select the **Prompts from file or textbox** script
3. Either paste prompts into the text box or load the file
4. Set your generation parameters
5. Click **Generate** — each prompt produces one or more images

### 5.10 Use Outpainting to Extend an Image

1. Go to **img2img** → **Inpaint** sub-tab
2. Upload your image
3. Select the **Outpainting mk2** script from the Script dropdown
4. Configure the number of pixels to extend on each side
5. Set denoising strength to `0.8–0.9`
6. Write a prompt matching the image's subject/style
7. Click **Generate** — the model fills in the new area coherently

### 5.11 SD Upscale (Tiled Upscaling)

For upscaling with Stable Diffusion refinement (better quality than plain upscalers):

1. Go to **img2img**
2. Upload the image to upscale
3. Select the **SD upscale** script
4. Choose a tile overlap (e.g., 64 pixels)
5. Choose an upscaler (e.g., `RealESRGAN_x4plus`)
6. Set scale factor to `2`
7. Set denoising strength to `0.2–0.4` (lower = closer to original)
8. Generate

### 5.12 Checkpoint Merging

Merge two or three models to combine their strengths:

1. Go to the **Checkpoint Merger** tab
2. Select **Primary model (A)** and **Secondary model (B)**
3. Optionally select a **Tertiary model (C)**
4. Choose interpolation method: **Weighted sum** or **Add difference**
5. Set the **Multiplier** (0 = all A, 1 = all B)
6. Choose output format (safetensors recommended)
7. Click **Merge**

The merged checkpoint appears in `models/Stable-diffusion/` and can be selected like any other model.

---

## 6. Troubleshooting

### Keyboard Shortcuts

Before diving into issues, know these shortcuts for controlling generation:

| Shortcut | Action |
|----------|--------|
| **Ctrl+Enter** | Start generation / restart |
| **Alt+Enter** | Skip current image in batch |
| **Esc** | Interrupt generation entirely |

### Error: `RuntimeError: Torch is not able to use GPU`

**Cause:** PyTorch was installed without CUDA support, or NVIDIA drivers are outdated.

**Solution:**
1. Check your NVIDIA driver version: `nvidia-smi`
2. Ensure you have CUDA-compatible drivers (525+ for CUDA 12.x)
3. Reinstall PyTorch with CUDA support by setting in `webui-user.sh` / `webui-user.bat`:

```bash
export TORCH_COMMAND="pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121"
```

4. Delete the `venv` folder and relaunch to force reinstall

**Prevention:** Always install NVIDIA drivers before the webui.

### Error: `Cannot import setuptools.build_meta`

**Cause:** Python 3.12+ removed `distutils`, which some dependencies still require.

**Solution:**
1. Install Python 3.10.6 alongside your current version
2. Update `webui-user.sh`/`webui-user.bat` to point `python_cmd` to Python 3.10
3. Delete the `venv` folder and relaunch

**Prevention:** Use Python 3.10.x for this project.

### Error: `No module named pip`

**Cause:** The Python installation is missing pip, or the venv was corrupted.

**Solution:**
1. Ensure pip is installed: `python -m ensurepip`
2. If the venv is corrupted, delete the `venv` folder and relaunch
3. On Linux, you may need: `sudo apt install python3-pip python3-venv`

**Prevention:** Use the official Python installer with pip included.

### Error: Python version is too recent

**Cause:** Dependencies (especially `torch`, `xformers`) don't support Python 3.12+.

**Solution:**
1. Install Python 3.10.6
2. Set `python_cmd=python3.10` in `webui-user.sh`
3. Delete `venv` and relaunch

**Prevention:** Stick to Python 3.10.x.

### Error: CLIP loading errors

**Cause:** Corrupted model download or HuggingFace connectivity issue.

**Solution:**
1. Delete the cached CLIP model (usually in `~/.cache/huggingface/`)
2. If behind a firewall, set `HF_ENDPOINT` to a mirror
3. Relaunch to re-download

**Prevention:** Ensure stable internet during first launch.

### Error: `AttributeError: 'ImageDraw' object has no attribute 'multiline_textsize'`

**Cause:** Pillow 10+ removed the deprecated `multiline_textsize` method.

**Solution:**
1. Pin Pillow to a compatible version:

```bash
pip install Pillow==9.5.0
```

2. Or update the webui to a version that supports Pillow 10+

**Prevention:** Let the webui manage its own dependencies via `requirements_versions.txt`.

### Error: `RuntimeError: Cannot add middleware after app started`

**Cause:** Extension or API configuration conflict during startup.

**Solution:**
1. Disable all extensions (rename `extensions` folder temporarily)
2. If it works, re-enable extensions one by one to find the conflict
3. Update the problematic extension or remove it

**Prevention:** Keep extensions updated.

> [!WARNING]
> When disabling extensions by renaming the folder, make sure to note the original name. Some extensions create configuration files that reference the folder name.

### Out of Memory Errors

**Cause:** Insufficient GPU VRAM for the requested operation.

**Solution:**
1. Add `--medvram` to `COMMANDLINE_ARGS` (moderate savings)
2. If still OOM, use `--lowvram` (significant savings, slower)
3. Reduce image dimensions (512x512 instead of 1024x1024)
4. Reduce batch size to 1
5. Add `--xformers` or `--opt-sdp-attention` for memory-efficient attention
6. Close other GPU-using applications

**Prevention:** Monitor VRAM with `nvidia-smi` and know your GPU's limits.

### NaN Images / Black Images

**Cause:** Numerical instability during generation, often with certain VAEs or half-precision mode.

**Solution:**
1. Add `--no-half-vae` to `COMMANDLINE_ARGS` (most common fix)
2. If still occurring, add `--no-half` (uses more VRAM)
3. Try a different VAE
4. Try `--upcast-sampling`

**Prevention:** Use `--no-half-vae` by default if you encounter this even once.

### Slow Generation Speed

**Cause:** Missing optimizations or sub-optimal configuration.

**Solution:**
1. Enable `--xformers` (NVIDIA GPUs, best speedup)
2. Or use `--opt-sdp-attention` (PyTorch 2.0+, no extra install)
3. Ensure you're not in `--lowvram` mode unnecessarily
4. Check that no other processes are using the GPU
5. Use appropriate resolution for your model (512px for SD 1.x, 1024px for SDXL)

**Prevention:** Always use `--xformers` or `--opt-sdp-attention`.

### Extensions Won't Install

**Cause:** Git connectivity issues, Python dependency conflicts, or permissions.

**Solution:**
1. Check internet connectivity
2. Try installing manually:

```bash
cd extensions
git clone <extension-url>
```

3. Check the console for specific pip errors
4. Some extensions need specific Python packages — install them manually

**Prevention:** Keep git updated and check extension compatibility before installing.

### Model Loading Failures

**Cause:** Corrupted download, incompatible format, or wrong config.

**Solution:**
1. Re-download the model file (check file size matches the source)
2. Prefer `.safetensors` format (safer and faster than `.ckpt`)
3. Ensure the correct config YAML exists for the model architecture
4. Check console output for specific error messages

**Prevention:** Always verify file integrity after downloading large models.

> [!CAUTION]
> The `.ckpt` format uses Python pickle, which can execute arbitrary code during loading. Always prefer `.safetensors` files, which are safe by design. If you must use `.ckpt` files, do not disable `--disable-safe-unpickle`.

### AMD GPU Issues

**Cause:** AMD GPUs require ROCm on Linux; Windows support is limited.

**Solution:**
1. Linux: install ROCm and use `--use-cpu` for unsupported operations
2. Set `TORCH_COMMAND` to install the ROCm version of PyTorch:

```bash
export TORCH_COMMAND="pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm5.6"
```

3. Some features (xformers) are NVIDIA-only; use `--opt-sdp-attention` instead
4. Check the webui wiki for AMD-specific guidance

**Prevention:** Verify your AMD GPU and ROCm version are in the PyTorch compatibility matrix.

### WebUI Won't Start

**Cause:** Various — dependency issues, port conflicts, corrupted venv.

**Solution:**
1. Read the console output carefully for the first error
2. Check if port 7860 is already in use: change with `--port 7861`
3. Delete `venv` folder and relaunch for a clean install
4. Ensure Python 3.10.x and git are on PATH
5. On Windows, run `webui-user.bat` from a terminal (not double-click) to see errors

**Prevention:** Keep a working `venv` backup before major updates.

---

## 7. FAQ

**Q: What GPUs are supported?**

NVIDIA GPUs with CUDA support are the primary target. Minimum 4 GB VRAM (GTX 1050 Ti class), recommended 8 GB+ (RTX 3060/4060 class). AMD GPUs work on Linux via ROCm. Intel Arc GPUs have experimental support. Apple Silicon (M1/M2/M3) works via MPS backend with the macOS launch script.

**Q: How much VRAM do I need?**

For SD 1.5 at 512x512: 4 GB minimum (with `--medvram`), 6 GB comfortable, 8 GB+ for batches and hires fix. For SDXL at 1024x1024: 8 GB minimum, 12 GB+ recommended. The `--medvram` and `--lowvram` flags reduce requirements at the cost of speed.

**Q: Can I use CPU only?**

Yes, add `--skip-torch-cuda-test --use-cpu all` to `COMMANDLINE_ARGS`. Generation will be extremely slow (minutes per image instead of seconds), but it works for testing or if you have no compatible GPU.

**Q: How do I update the webui?**

```bash
cd stable-diffusion-webui
git pull
```

Then relaunch. The startup script handles dependency updates automatically. For a clean update, delete the `venv` folder before relaunching.

**Q: Where are generated images saved?**

By default:
- txt2img: `outputs/txt2img-images/`
- img2img: `outputs/img2img-images/`
- Extras: `outputs/extras-images/`
- Grids: `outputs/txt2img-grids/` and `outputs/img2img-grids/`

These paths are configurable in Settings → Saving paths.

**Q: How do I add custom models?**

Place model files in the appropriate directory:
- Checkpoints (`.safetensors`, `.ckpt`): `models/Stable-diffusion/`
- VAEs: `models/VAE/`
- LoRAs: `models/Lora/`
- Embeddings: `embeddings/`
- Upscalers (ESRGAN etc.): `models/ESRGAN/`

Click the refresh button next to the model dropdown to detect new files without restarting.

**Q: What's the difference between samplers?**

Samplers control the denoising algorithm. Key distinctions:

- **Euler / Euler a**: fast, good baseline. "a" = ancestral (adds randomness each step)
- **DPM++ 2M Karras**: excellent quality-to-speed ratio, widely recommended
- **DPM++ SDE Karras**: good for detailed images, slightly slower
- **DDIM**: deterministic, good for img2img and low step counts
- **UniPC**: fast convergence, good results in fewer steps
- **LCM**: designed for LCM-LoRA, produces results in 4–8 steps

Ancestral samplers (marked with "a") never fully converge — increasing steps continues changing the image. Non-ancestral samplers converge to a final result.

**Q: How do I use SDXL?**

1. Download an SDXL checkpoint (e.g., `sd_xl_base_1.0.safetensors`) and place it in `models/Stable-diffusion/`
2. Optionally download the SDXL refiner model
3. Select the SDXL checkpoint from the dropdown
4. Set resolution to 1024x1024 (SDXL's native resolution)
5. Generate as usual — the webui automatically detects the model architecture

SDXL requires more VRAM than SD 1.5 (8 GB+ recommended).

**Q: Can I run it on a server or cloud?**

Yes. Use `--listen` to bind to all interfaces and `--port` to set the port. For security, add `--gradio-auth user:password`. For public access, use `--share` (Gradio tunnel) or `--ngrok` with a token. For API-only access, use `--nowebui --api`.

**Q: How do I use the API?**

Launch with `--api` flag. The API is documented at `http://127.0.0.1:7860/docs`. Key endpoints:
- `POST /sdapi/v1/txt2img` — text-to-image
- `POST /sdapi/v1/img2img` — image-to-image
- `GET /sdapi/v1/sd-models` — list models
- `POST /sdapi/v1/options` — change settings
- `GET /sdapi/v1/progress` — check generation progress

Use `--api-auth user:pass` for API authentication.

**Q: What is --xformers?**

The `--xformers` flag enables the [xformers](https://github.com/facebookresearch/xformers) library for memory-efficient cross-attention. It reduces VRAM usage and increases speed on NVIDIA GPUs. If xformers fails to install, use `--opt-sdp-attention` as an alternative (requires PyTorch 2.0+).

**Q: How do I disable the NSFW safety checker?**

The webui does not include a built-in NSFW filter by default. If an extension adds one, disable it from the Extensions tab. The `--disable-safe-unpickle` flag is unrelated — it controls pickle file safety checks, not content filtering.

**Q: Can I use multiple GPUs?**

The webui does not natively support multi-GPU generation. Each instance uses one GPU. To use a specific GPU, set the `CUDA_VISIBLE_DEVICES` environment variable:

```bash
export CUDA_VISIBLE_DEVICES=1  # use second GPU
```

For parallel processing, run multiple instances on different ports and GPUs.

**Q: How do I roll back to an older version?**

```bash
cd stable-diffusion-webui
git log --oneline -20    # find the commit you want
git checkout <commit-hash>
```

Delete the `venv` folder and relaunch to ensure dependencies match the older version. Back up your `config.json` and `ui-config.json` before rolling back.

**Q: What is the config.json file?**

`config.json` in the webui root stores all settings configured through the UI's Settings tab. It is created automatically on first settings save. You can edit it directly (with the webui stopped) or back it up before making changes. `ui-config.json` stores UI element defaults (dropdown selections, slider ranges).

---

## Appendix: Reference Tables

### Available Samplers

**K-diffusion samplers:** Euler, Euler a, LMS, Heun, DPM2, DPM2 a, DPM++ 2S a, DPM++ 2M, DPM++ SDE, DPM++ 2M SDE, DPM++ 3M SDE, DPM fast, DPM adaptive, LMS Karras, DPM2 Karras, DPM2 a Karras, DPM++ 2S a Karras, DPM++ 2M Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, DPM++ 3M SDE Karras, DPM++ 2M SDE Exponential, DPM++ 3M SDE Exponential, Restart

**CompVis samplers:** DDIM, PLMS, UniPC

**LCM sampler:** LCM

### Supported Model Architectures

| Architecture | Config File | Native Resolution |
|-------------|-------------|-------------------|
| SD 1.x | `v1-inference.yaml` | 512x512 |
| SD 1.x Inpainting | `v1-inpainting-inference.yaml` | 512x512 |
| SD 2.x | `v2-inference.yaml` / `v2-inference-v.yaml` | 768x768 |
| SDXL | `sd_xl_base.yaml` / `sd_xl_inpaint.yaml` | 1024x1024 |
| SD3 | `sd3-inference.yaml` | 1024x1024 |
| Alt-Diffusion | `alt-diffusion-inference.yaml` | 512x512 |
| InstructPix2Pix | `instruct-pix2pix.yaml` | 512x512 |

### Built-in Scripts

| Script | Tab | Purpose |
|--------|-----|---------|
| Prompts from file or textbox | txt2img, img2img | Batch generate from a list of prompts |
| Prompt matrix | txt2img, img2img | Generate combinations of prompt segments |
| X/Y/Z plot | txt2img, img2img | Parameter comparison grid |
| SD upscale | img2img | Tiled upscaling with SD refinement |
| Outpainting mk2 | img2img | Extend image borders |
| Poor man's outpainting | img2img | Simpler outpainting method |
| Loopback | img2img | Iterative img2img (feed output back) |
| img2img alternative test | img2img | Alternative img2img processing |
| Run custom code | txt2img, img2img | Execute arbitrary Python code |

---

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