Implementation:AUTOMATIC1111 Stable diffusion webui Webui Shell Launcher

Knowledge Sources	AUTOMATIC1111_Stable_diffusion_webui
Domains	Launcher, Installation, Shell
Last Updated	2025-05-15 00:00 GMT

Overview

The webui.sh shell launcher is the primary entry point for Linux and macOS users, handling environment setup, dependency validation, Python virtual environment management, GPU-specific PyTorch installation, and launching the application with automatic restart support.

Description

This Bash script performs the following stages:

Configuration Loading:

Sources webui-macos-env.sh on macOS for platform-specific defaults
Sources webui-user.sh to read user-customizable variables (install_dir, clone_dir, python_cmd, venv_dir, LAUNCH_SCRIPT, TORCH_COMMAND, COMMANDLINE_ARGS, etc.)
Sets defaults for install directory, clone directory, Python command (python3.10 or python3), git executable, and venv directory

Security and Platform Checks:

Prevents running as root (unless -f flag is passed)
Rejects 32-bit operating systems
Validates that git and Python are installed and available
Validates that python3-venv is available when venv support is enabled

GPU Detection and PyTorch Configuration:

Detects GPU type via lspci output
Configures AMD GPU support with appropriate ROCm PyTorch builds for Navi 1 (with Python version-specific wheels), Navi 2, Navi 3, and Renoir APUs via HSA_OVERRIDE_GFX_VERSION and TORCH_COMMAND
Falls back to ROCm 5.7 for generic AMD GPUs
Supports Huawei NPU via torch_npu

Repository and Environment Setup:

Clones the repository if not already present, or uses the existing directory
Creates and activates a Python virtual environment (unless disabled with venv_dir="-")
Upgrades pip on first launch

TCMalloc Optimization:

The prepare_tcmalloc() function attempts to locate and preload TCMalloc on Linux for improved CPU memory usage
Checks glibc version to handle libpthread linking differences (glibc < 2.34 vs >= 2.34)
Searches for both libtcmalloc_minimal and libtcmalloc variants

Launch Loop:

Runs launch.py (or uses accelerate launch if ACCELERATE is set) in a loop
Supports automatic restart by checking for the existence of tmp/restart file
Disables sentry error reporting and pip reinstallation of existing packages

Usage

Users run this script directly from the terminal to start the web UI. It is the recommended way to launch on Linux and macOS systems. User-specific configuration should be placed in webui-user.sh rather than modifying this script directly.

Code Reference

Source Location

Repository: AUTOMATIC1111_Stable_diffusion_webui
File: webui.sh
Lines: 1-304

Signature

#!/usr/bin/env bash

# Key variables (set via webui-user.sh or defaults):
# install_dir    - Installation directory (default: script directory)
# clone_dir      - Repository subdirectory (default: "stable-diffusion-webui")
# python_cmd     - Python executable (default: "python3.10" or "python3")
# venv_dir       - Virtual environment directory (default: "venv", "-" to disable)
# GIT            - Git executable (default: "git")
# LAUNCH_SCRIPT  - Python launch script (default: "launch.py")
# TORCH_COMMAND  - Custom PyTorch install command
# ACCELERATE     - Set to "True" to use HuggingFace Accelerate

prepare_tcmalloc()   # Attempts to preload TCMalloc for memory optimization

Import

# Run directly from terminal:
bash webui.sh

# With root override:
bash webui.sh -f

# User configuration (in webui-user.sh):
export COMMANDLINE_ARGS="--xformers --api"
export TORCH_COMMAND="pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121"

I/O Contract

Inputs

Name	Type	Required	Description
webui-user.sh	file	No	User configuration file sourced at startup for custom variables
webui-macos-env.sh	file	No	macOS-specific environment defaults (sourced automatically on Darwin)
-f	flag	No	Command line flag to allow running as root
COMMANDLINE_ARGS	env var	No	Additional arguments passed to launch.py
TORCH_COMMAND	env var	No	Custom PyTorch installation command (overrides GPU auto-detection)
ACCELERATE	env var	No	Set to "True" to launch via HuggingFace Accelerate
venv_dir	env var	No	Virtual environment directory path; set to "-" to disable venv

Outputs

Name	Type	Description
Running webui	process	The launched Python process running launch.py with the configured environment
venv/	directory	Python virtual environment created on first run (unless disabled)
tmp/restart	file	Sentinel file checked by the restart loop; its presence triggers a relaunch

Usage Examples

# Basic launch on Linux
./webui.sh

# Launch with root permissions (not recommended)
./webui.sh -f

# Custom configuration in webui-user.sh:
install_dir="/opt/sd"
clone_dir="stable-diffusion-webui"
python_cmd="python3.11"
venv_dir="venv"
export COMMANDLINE_ARGS="--xformers --api --listen"
export TORCH_COMMAND="pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121"

# Disable virtual environment
venv_dir="-"

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment