Implementation:AUTOMATIC1111 Stable diffusion webui ScriptPostprocessingRunner run

Knowledge Sources	stable-diffusion-webui
Domains	Software Architecture, Plugin Systems, Image Processing, Pipeline Design
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for executing a pipeline of postprocessing scripts on an image in configurable order provided by stable-diffusion-webui.

Description

ScriptPostprocessingRunner.run() orchestrates the execution of all registered postprocessing scripts on a PostprocessedImage wrapper. The method operates in two phases:

Phase 1 (First Pass): All scripts are called via process_firstpass() in their configured order. This allows scripts to examine the image, read shared state set by earlier scripts, and declare intended transformations (e.g., target dimensions for upscaling) without modifying the image itself.

Phase 2 (Processing): All scripts are called via process() in order. For each script, every image in the accumulated all_images list is processed (unless it has disable_processing = True). After each image is processed, any new extra_images it produced are moved to the global list for subsequent scripts to process. This branching mechanism allows a single input to produce multiple output variants.

The PostprocessedImage class wraps a PIL Image with an info dictionary for metadata, a shared object for cross-script communication (target dimensions), an extra_images list for spawning additional outputs, a nametags list for filename suffix generation, a disable_processing flag, and an optional caption string.

Scripts are ordered using scripts_in_preferred_order(), which respects the user's configured postprocessing_operation_order and filters out scripts listed in postprocessing_disable_in_extras.

Usage

Use ScriptPostprocessingRunner.run() indirectly through the run_postprocessing() function. It is called automatically for every image in the postprocessing pipeline. Direct usage is needed when building custom postprocessing workflows outside the standard Extras tab.

Code Reference

Source Location

• Repository: stable-diffusion-webui
• File: modules/scripts_postprocessing.py
• Lines: 172-208

Signature

# Runner (modules/scripts_postprocessing.py:L172-208)
class ScriptPostprocessingRunner:
    def run(self, pp: PostprocessedImage, args) -> None:
        ...

# PostprocessedImage wrapper (modules/scripts_postprocessing.py:L14-53)
class PostprocessedImage:
    def __init__(self, image):
        self.image = image
        self.info = {}
        self.shared = PostprocessedImageSharedInfo()
        self.extra_images = []
        self.nametags = []
        self.disable_processing = False
        self.caption = None

# Shared state dataclass (modules/scripts_postprocessing.py:L8-11)
@dataclasses.dataclass
class PostprocessedImageSharedInfo:
    target_width: int = None
    target_height: int = None

# Script base class (modules/scripts_postprocessing.py:L56-98)
class ScriptPostprocessing:
    name = None
    order = 1000
    def process_firstpass(self, pp: PostprocessedImage, **args): ...
    def process(self, pp: PostprocessedImage, **args): ...

Import

from modules.scripts_postprocessing import ScriptPostprocessingRunner, PostprocessedImage

I/O Contract

Inputs

Name	Type	Required	Description
pp	PostprocessedImage	Yes	Wrapper containing the input PIL Image, an empty info dict, shared state, and empty extra_images list
args	list	Yes	Flat list of UI control values. Each script owns a contiguous slice [args_from:args_to] that is mapped back to named keyword arguments based on the script's registered controls.

Outputs

Name	Type	Description
return	None	The method modifies pp in place. After execution: pp.image contains the processed primary image, pp.info contains accumulated metadata from all scripts, and pp.extra_images contains any additional images produced by the pipeline.

Usage Examples

Basic Usage

from modules import scripts, scripts_postprocessing
from PIL import Image

# Create a PostprocessedImage wrapper
image = Image.open("input.png")
pp = scripts_postprocessing.PostprocessedImage(image)

# Run the full postprocessing script pipeline
# args is the flat list of UI control values from the Extras tab
scripts.scripts_postproc.run(pp, args)

# Access results
processed_image = pp.image
metadata = pp.info
extra_outputs = pp.extra_images

Creating Args Programmatically

from modules import scripts

# Build args for specific scripts using create_args_for_run
args = scripts.scripts_postproc.create_args_for_run({
    "Upscale": {
        "upscale_enabled": True,
        "upscale_mode": 0,
        "upscale_by": 4.0,
        "max_side_length": 0,
        "upscale_to_width": 512,
        "upscale_to_height": 512,
        "upscale_crop": False,
        "upscaler_1_name": "R-ESRGAN 4x+",
        "upscaler_2_name": "None",
        "upscaler_2_visibility": 0.0,
    },
    "CodeFormer": {
        "enable": True,
        "codeformer_visibility": 1.0,
        "codeformer_weight": 0.5,
    },
})

pp = scripts_postprocessing.PostprocessedImage(image)
scripts.scripts_postproc.run(pp, args)

Related Pages

Implements Principle

• Principle:AUTOMATIC1111_Stable_diffusion_webui_Postprocessing_script_execution