Implementation:AUTOMATIC1111 Stable diffusion webui Options System

Knowledge Sources	AUTOMATIC1111_Stable_diffusion_webui
Domains	Configuration, Settings Management, UI Infrastructure
Last Updated	2025-05-15 00:00 GMT

Overview

Defines the Options class that manages all user-configurable settings, handling persistence to JSON, type validation, UI section organization, and change callbacks.

Description

This module provides the complete settings infrastructure for the WebUI:

• OptionInfo: Metadata class for each setting, storing default value, label, UI component type and arguments, section/category placement, onchange callback, infotext mapping, API restriction flag, and HTML comments for the UI. Provides fluent builder methods (link(), js(), info(), html(), needs_restart(), needs_reload_ui()) for augmenting the setting display.

• OptionHTML: A subclass of OptionInfo that renders as an HTML info block in the settings UI, not stored as a setting.

• options_section: A helper function that assigns section identifiers (and optional category IDs) to a dictionary of settings options.

• Options: The core settings manager that uses __setattr__ and __getattr__ overrides to provide attribute-style access to settings stored in a data dictionary. Key capabilities include:
  • Persistence: save() writes to JSON, load() reads from JSON with migration logic for legacy settings (VAE defaults, quicksettings list, ui_reorder).
  • Validation: Type checking against defaults, frozen settings enforcement (--freeze-settings, --freeze-settings-in-sections, --freeze-specific-settings), restricted path options (--hide_ui_dir_config), and hidden component protection.
  • Change callbacks: The set() method triggers onchange callbacks with automatic rollback on error.
  • UI support: dumpjson() serializes all settings with metadata for the frontend, reorder() sorts settings by category and section.
  • Extension support: add_option() allows extensions to register new settings dynamically.

• OptionsCategory and OptionsCategories: A registry system for organizing settings into named categories (e.g., "postprocessing", "training") that group multiple sections together.

Usage

Use this module as the foundation for all WebUI settings. The global shared.opts object is an instance of Options, and all code accesses settings through it. Extensions add their own settings via shared.opts.add_option() in their on_ui_settings callback.

Code Reference

Source Location

• Repository: AUTOMATIC1111_Stable_diffusion_webui
• File: modules/options.py
• Lines: 1-336

Signature

class OptionInfo:
    def __init__(self, default=None, label="", component=None,
                 component_args=None, onchange=None, section=None,
                 refresh=None, comment_before='', comment_after='',
                 infotext=None, restrict_api=False, category_id=None):

class Options:
    def __init__(self, data_labels: dict[str, OptionInfo], restricted_opts):
    def __setattr__(self, key, value):
    def __getattr__(self, item):
    def set(self, key, value, is_api=False, run_callbacks=True):
    def save(self, filename):
    def load(self, filename):
    def add_option(self, key, info):
    def reorder(self):
    def dumpjson(self):
    def cast_value(self, key, value):

def options_section(section_identifier, options_dict):

Import

from modules.options import Options, OptionInfo, OptionHTML, options_section

I/O Contract

Inputs

Name	Type	Required	Description
data_labels	dict[str, OptionInfo]	Yes	Dictionary mapping setting keys to their OptionInfo metadata
restricted_opts	set	Yes	Set of option keys restricted by --hide_ui_dir_config
key	str	Yes	Setting key to get or set
value	any	No	Value to assign to a setting
filename	str	No	Path to JSON config file for save/load

Outputs

Name	Type	Description
value	any	The current value of a setting when accessed via attribute or get
changed	bool	Whether the set() method actually changed the value (True/False)
json_str	str	JSON string of all settings and metadata from dumpjson()

Usage Examples

from modules.options import Options, OptionInfo, options_section

# Define settings with sections
data_labels = options_section(('generation', 'Generation'), {
    "steps": OptionInfo(20, "Sampling steps"),
    "cfg_scale": OptionInfo(7.0, "CFG Scale"),
    "sampler_name": OptionInfo("Euler", "Sampling method"),
})

# Create the Options object
opts = Options(data_labels, restricted_opts=set())

# Access settings as attributes
print(opts.steps)       # 20
print(opts.cfg_scale)   # 7.0

# Change a setting with callback
opts.set("steps", 30)

# Save/load settings
opts.save("config.json")
opts.load("config.json")

# Extensions can add new settings
opts.add_option("my_extension_option",
    OptionInfo(True, "Enable my feature",
               section=('my_ext', 'My Extension')))

Related Pages

• Principle:AUTOMATIC1111_Stable_diffusion_webui_Settings_Management