Getting started

This page covers how to get a working development checkout of stable-diffusion-webui on your machine. End-user installation (the "download a zip and double-click" path) is documented on the GitHub wiki; the section below is for contributors.

Prerequisites

• Python 3.10.6 is the recommended interpreter. 3.11 works on most platforms; 3.9 is supported for compatibility (see pyproject.toml — target-version = "py39"). 3.12+ may break PyTorch.
• Git with submodule support.
• A GPU is strongly recommended. The app supports NVIDIA (CUDA), AMD (ROCm on Linux, DirectML on Windows), Apple Silicon (MPS), Intel discrete/integrated (IPEX), Ascend NPUs, and CPU-only mode.
• At least 8 GB of VRAM for SD 1.5 / SD 2.1 models at default settings; less with --medvram or --lowvram.
• ~25 GB of free disk for dependencies, models, and cached repositories.

First-run install

Clone the repository and run the launcher script:

git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
./webui.sh                              # Linux / macOS
# or
webui-user.bat                          # Windows

On the first run webui.sh will:

1. Create a venv/ virtual environment using python3.10 if available, otherwise python3.
2. Run python launch.py, which calls prepare_environment() from modules/launch_utils.py.
3. Pip-install pinned dependencies from requirements_versions.txt and a platform-appropriate PyTorch.
4. Clone four upstream repositories into repositories/: stable-diffusion-stability-ai, BLIP, k-diffusion, generative-models.
5. Download the default Stable Diffusion 1.5 checkpoint to models/Stable-diffusion/ if no checkpoint is present.
6. Start a Gradio server on http://127.0.0.1:7860.

Subsequent runs skip the install steps and just start the server, which usually takes 10–30 seconds depending on the model.

Useful command-line flags

A complete list is in modules/cmd_args.py; pass them via COMMANDLINE_ARGS in webui-user.sh (Linux/Mac) or webui-user.bat (Windows). Common flags during development:

Flag	Purpose
--api	Expose the FastAPI routes alongside the UI
--nowebui	Run as a headless API server (no Gradio UI)
--listen	Bind to 0.0.0.0 instead of 127.0.0.1
--port 7861	Run on a non-default port
--medvram / --lowvram	Reduce VRAM use at the cost of speed
--use-cpu all	Run everything on CPU (slow but useful for tests)
--xformers	Enable xFormers cross-attention if installed
--ckpt-dir <path>	Use models from a different directory
--data-dir <path>	Store user data (config, outputs) outside the repo
--no-half	Disable fp16 for the UNet (helps debug NaN issues)
--allow-code	Enable the "run arbitrary Python" script (use with care)
--gradio-debug	Enable Gradio's verbose debug output
--api-server-stop	Allow the API to shut down the server (for tests)

Running the test suite

Tests live in test/ and exercise the API, not the UI. The CI workflow .github/workflows/run_tests.yaml shows the canonical invocation.

# 1. Install test dependencies
pip install -r requirements-test.txt

# 2. Start a test server in the background
python launch.py \
    --skip-prepare-environment \
    --skip-torch-cuda-test \
    --test-server \
    --do-not-download-clip \
    --no-half \
    --disable-opt-split-attention \
    --use-cpu all \
    --api-server-stop &

# 3. Wait for the server to be reachable, then run pytest
python -m pytest -vv --verify-base-url test/

# 4. Stop the server
curl -X POST http://127.0.0.1:7860/sdapi/v1/server-stop

--test-server makes the server skip auto-launching the browser and load a smaller stub model. --use-cpu all is required because GitHub-hosted runners do not have a GPU. See how-to-contribute/testing.md for more.

Linting

# Python
ruff check .                            # config in pyproject.toml

# JavaScript
npm install
npm run lint                            # eslint .

Ruff is configured under [tool.ruff.lint] in pyproject.toml with the B, C, I, W rule sets. ESLint config is in .eslintrc.js.

What lives where

.
├── launch.py                # entry point — calls modules/launch_utils.py
├── webui.py                 # the actual Gradio + FastAPI server
├── webui.sh / webui.bat     # OS-specific wrappers (venv + COMMANDLINE_ARGS)
├── webui-user.sh/.bat       # user-editable env vars
├── webui-macos-env.sh       # MPS/Apple Silicon defaults
├── modules/                 # ~120 Python modules
│   ├── api/                 # FastAPI routes + Pydantic models
│   ├── hypernetworks/       # legacy hypernetwork training
│   ├── models/              # ldm-style configs (sd3, depth)
│   ├── processing_scripts/  # alwayson built-in scripts (seed, sampler, refiner, comments)
│   └── textual_inversion/   # embedding training
├── extensions-builtin/      # Lora, LDSR, SwinIR, ScuNET, hypertile, etc.
├── extensions/              # user extensions (gitignored)
├── javascript/              # browser-side JS
├── scripts/                 # legacy script entry points
├── configs/                 # SD model YAML configs
├── models/                  # downloaded checkpoints (gitignored)
├── embeddings/              # textual inversion embeddings
├── localizations/           # JSON translations
├── style.css                # webui styling
├── script.js                # client bootstrap
├── test/                    # pytest API tests
└── requirements*.txt        # pinned and floating dependency lists

The systems/ section walks each major code area in depth. If something seems missing, check the glossary for project-specific names.