Implementation:AUTOMATIC1111 Stable diffusion webui Scripts System
| Knowledge Sources | |
|---|---|
| Domains | Extensibility, Scripts, Pipeline |
| Last Updated | 2025-05-15 00:00 GMT |
Overview
The scripts system implements the core extension framework that allows both built-in features and third-party extensions to hook into the image generation pipeline through a lifecycle-based Script base class and a ScriptRunner orchestrator.
Description
This module defines the Script base class that all scripts (built-in and extension) must subclass to participate in image generation. The Script class provides a comprehensive set of lifecycle hooks: setup, before_process, process, before_process_batch, process_batch, postprocess_batch, postprocess_batch_list, post_sample, on_mask_blend, postprocess_image, postprocess, before_hr, and run. Each hook is called at a specific point during generation, allowing scripts to modify prompts, latents, images, and processing parameters.
The ScriptRunner class discovers and loads scripts from the main scripts directory and from active extensions, sorts them topologically based on declared dependencies (requires, load_before, load_after), manages their Gradio UI components, and dispatches lifecycle callbacks in the correct order. It maintains separate lists for selectable scripts (user picks one from a dropdown) and always-on scripts (run every time).
Data classes such as MaskBlendArgs, PostSampleArgs, PostprocessImageArgs, PostProcessMaskOverlayArgs, and PostprocessBatchListArgs provide typed context objects passed between the pipeline and script hooks.
Helper functions include list_scripts for discovering script files with dependency resolution, load_scripts for dynamically importing script modules and instantiating ScriptRunner instances, and wrap_call for safe error-handled invocation of script methods.
Usage
Use this module when building a new script extension by subclassing Script and overriding the desired lifecycle hooks. The ScriptRunner is used internally by the processing pipeline to invoke all registered scripts at each stage of image generation. Extension authors interact with this system to add custom processing, UI controls, and infotext fields.
Code Reference
Source Location
- Repository: AUTOMATIC1111_Stable_diffusion_webui
- File: modules/scripts.py
- Lines: 1-1040
Signature
class Script:
def title(self) -> str: ...
def ui(self, is_img2img) -> list: ...
def show(self, is_img2img) -> bool: ...
def run(self, p, *args) -> Processed: ...
def setup(self, p, *args): ...
def before_process(self, p, *args): ...
def process(self, p, *args): ...
def before_process_batch(self, p, *args, **kwargs): ...
def process_batch(self, p, *args, **kwargs): ...
def postprocess_batch(self, p, *args, **kwargs): ...
def postprocess_image(self, p, pp: PostprocessImageArgs, *args): ...
def postprocess(self, p, processed, *args): ...
def before_hr(self, p, *args): ...
class ScriptRunner:
def __init__(self): ...
def initialize_scripts(self, is_img2img): ...
def setup_ui(self) -> list: ...
def run(self, p, *args) -> Processed: ...
def load_scripts(): ...
def list_scripts(scriptdirname, extension, *, include_extensions=True) -> list: ...
Import
from modules.scripts import Script, ScriptRunner, AlwaysVisible
from modules.scripts import scripts_txt2img, scripts_img2img
from modules.scripts import load_scripts
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| p | StableDiffusionProcessing | Yes | The processing object containing generation parameters, passed to all lifecycle hooks |
| *args | tuple | Yes | Values from the script's Gradio UI components, passed to lifecycle hooks |
| **kwargs | dict | No | Additional context such as batch_number, prompts, seeds, subseeds (for batch hooks) |
| is_img2img | bool | Yes | Whether the script is being initialized for the img2img tab |
| scriptdirname | str | Yes | Directory name to scan for scripts (e.g. "scripts") |
| extension | str | Yes | File extension filter (e.g. ".py") |
Outputs
| Name | Type | Description |
|---|---|---|
| Processed | modules.processing.Processed | Result object returned by script.run() containing generated images and metadata |
| scripts_list | list[ScriptFile] | Ordered list of discovered script files after dependency resolution |
| inputs | list | List of Gradio components registered by all scripts for the current tab |
Usage Examples
# Defining a custom script extension
from modules.scripts import Script, AlwaysVisible
class MyCustomScript(Script):
def title(self):
return "My Custom Script"
def show(self, is_img2img):
return AlwaysVisible
def ui(self, is_img2img):
import gradio as gr
strength = gr.Slider(label="Effect Strength", minimum=0, maximum=1, value=0.5)
return [strength]
def process(self, p, strength):
# Modify processing parameters before generation
p.extra_generation_params["MyScript"] = strength
def postprocess_image(self, p, pp, strength):
# Modify each generated image after generation
pass