Built-in scripts

Active contributors: AUTOMATIC1111, w-e-w, missionfloyd

Purpose

The repository ships ~12 user-facing scripts under scripts/ — non-alwayson scripts users pick from the Script dropdown on the txt2img / img2img / Extras tabs. They predate the extension system and remain the canonical examples of how scripts work.

Alwayson built-ins (refiner, sampler, seed, comments) live in modules/processing_scripts/ and are documented in systems/scripts-and-extensions.md.

What's in scripts/

File	Tab	What it does
xyz_grid.py	txt2img + img2img	Vary up to three parameters in a 3D grid; produces an image grid per "Z" slice. The largest user script in the repo.
prompt_matrix.py	txt2img + img2img	Take a prompt with | separators, generate every subset combination, lay out as a grid.
prompts_from_file.py	txt2img	Run a list of prompts from a file or text box; supports per-prompt parameter overrides.
loopback.py	img2img	Feed each output back as next input N times; ramps denoising strength.
outpainting_mk_2.py	img2img	Mirror-noise-based outpainting (parlance-zz approach).
poor_mans_outpainting.py	img2img	Simple inpainting-based outpainting; older.
sd_upscale.py	img2img	Tile-based "render at higher res" using img2img on each tile.
img2imgalt.py	img2img	Reverse-Euler "img2img alternative" by Doggettx — back-derive noise then re-sample.
custom_code.py	txt2img + img2img	Run user-supplied Python code with access to p. Disabled unless --allow-code is set.
postprocessing_codeformer.py	Extras	Wraps CodeFormer face restoration as a postprocessor.
postprocessing_gfpgan.py	Extras	Wraps GFPGAN face restoration as a postprocessor.
postprocessing_upscale.py	Extras	The main upscale step — supports two stacked upscalers and visibility blending.

X/Y/Z plot — the example to learn from

scripts/xyz_grid.py is the most-cited script and a good template for non-trivial scripts. It demonstrates:

• A pluggable axis system (AxisOption subclasses) so each parameter you can vary is a self-contained type with apply(), format_value(), and optional confirm() validation.
• CSV input parsing (the Sweep and CSV-list helpers).
• Reuse of the main process_images for each grid cell.
• Per-image and final-grid infotext annotation.
• A "Swap axes" button rewired through Gradio.
• Conditionally registered axes (e.g., the "Hires upscaler" axis appears only on txt2img).

If you're learning the script API, start by reading xyz_grid.py's Script subclass at the bottom of the file and tracing one parameter (say "CFG Scale") through apply_field, AxisOption, and cell().

Custom code script

custom_code.py runs user-supplied Python with p exposed in scope. It is gated behind --allow-code and shows a warning. Anyone running a public-facing webui should leave this disabled — the script can os.system() whatever it wants.

How a script ends up in the dropdown

Boot path:

1. scripts.load_scripts() walks scripts/ and extensions*/scripts/.
2. For each Python file, it imports the module and finds subclasses of Script (and ScriptPostprocessing).
3. Per-tab ScriptRunner.initialize_scripts(is_img2img) filters by Script.is_txt2img / is_img2img and Script.show(). Those whose show() returns True go into the Script dropdown.
4. The user picks one; ScriptRunner.run(p, *args) calls the script's run(p, *args) method, which is the only entry point one-shot scripts implement.

run() returns a Processed (typically by calling process_images(p) itself) and that becomes the page's response.

Extras tab postprocessors

Extras-tab built-ins use the same ScriptPostprocessing base as third-party extensions. The chain is fixed by the order field on each — postprocessing_upscale.py runs at order 1000, the face restorers at 2000.

Integration points

• A script is a class, not a module. You can put multiple Script subclasses in the same file but the convention is one per file.
• Scripts are instantiated once at boot. Any heavy state should be lazy-loaded inside run() or process() so it doesn't fire on every reload.
• Script.run(p, *args) returns whatever it wants as long as it's a Processed. That's what gets gallery-displayed.

Entry points for modification

• Add a new one-shot variant — copy the smallest existing script that fits (prompt_matrix.py is good for "loop variations") and modify.
• Tweak X/Y/Z — most additions to that script are new AxisOption entries near the top. The processing logic is generic.
• Replace a built-in with an alwayson — the trade-off is "user has to opt in via dropdown" vs "always present, can interfere". One-shot scripts are usually preferable for parameter-sweep tools.