Dev: Script & Extensions Guide

Common Mistakes

Execution on import: Keep extension modules import-safe. Do not run work at import time (except trivial and allowed install.py setup). Put logic inside functions/classes and run it from app callbacks. Import-time execution can slow startup or crash the server.
Keeping all Python code in /scripts: Use /scripts as the entry point only. Split implementation into other modules outside /scripts and import them from the entry file. Otherwise, server startup may load and execute files repeatedly.
Browser namespace collisions: JavaScript files are loaded into a shared global namespace. Use unique prefixes for functions and variables instead of generic names such as log().
Incorrect callback usage: Choose callbacks carefully. onUiLoaded runs once, while onUiUpdated can run many times during startup. Running heavy initialization in a frequently called callback causes slow page loads and repeated work. This applies to both Python and JavaScript.
Executing code when disabled: If an extension is disabled, callbacks should early-exit and do no work. Otherwise, you can add avoidable delays before, during, or after generation.
Unsafe references: Treat callback data and server variables as optional unless guaranteed. For example, image.info may not exist for every image. Use safe access helpers such as get() or getattr(). The same applies to settings: do not assume they never change.
Unsafe patching: Extensions can patch server methods, but patch carefully. For example, replacing forward should avoid global behavior that breaks other extensions.
Running platform-specific code: Avoid hard-coding platform/backend behavior. Do not force values such as torch.to('cuda') or torch.float16. Use server variables such as devices.device and devices.dtype.
Assuming values: Do not assume install paths or runtime values. For example, an extension may not be located under /extensions.

Many popular extensions still hit several of these issues. Remember that installing an extension grants it broad access, so implementation quality and safety matter.

Extension vs Script

Script is a single module that implements script callbacks.
Script objects inherit from Script and implement required methods plus optional callbacks.
Extension is a larger implementation with its own folder structure.
Extension can contain multiple scripts or operate through its own hooks.

Extension Folder Structure

Note: all files listed below are optional.

/preload.py Loaded early during startup to add command line arguments. Define preload(parser: argparser) and avoid other work at this stage.
/install.py Loaded early during startup to install optional requirements. Use supported helpers such as launch.run_pip. Avoid direct OS calls or unrelated work.
/javascript/*.js JavaScript files are injected as-is. Keep files limited to defining functions/variables and registering callbacks.
/style.css Style is loaded as-is.
/scripts/*.py Main extension entry points loaded by the server during startup. Keep files focused on definitions and callback registration.