Implementation:AUTOMATIC1111 Stable diffusion webui Upscaler upscale

Knowledge Sources	stable-diffusion-webui
Domains	Super-Resolution, Deep Learning, Image Processing
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for upscaling images to a target scale factor using pluggable super-resolution models provided by stable-diffusion-webui.

Description

The Upscaler class defines the abstract base for all upscaling backends in the WebUI. Its upscale() method handles iterative application of the underlying model to reach a target scale factor, while the abstract do_upscale() method performs a single upscaling pass using the specific model implementation.

The upscale() method computes target dimensions aligned to multiples of 8, then iteratively calls do_upscale() up to 3 times until the image meets or exceeds the target size. If the model fails to increase image dimensions (indicating a no-op or error), the loop breaks early. A final Lanczos resize ensures the output matches the exact target dimensions.

The tiled upscaling infrastructure in upscaler_utils.py provides two strategies: upscale_with_model() operates in Pillow space by splitting the image into a grid of overlapping tiles and reassembling them with alpha-mask blending, while tiled_upscale_2() operates in PyTorch tensor space with weight accumulation for smoother overlap transitions.

Built-in subclasses include UpscalerNone (identity pass-through), UpscalerLanczos (Lanczos interpolation), and UpscalerNearest (nearest-neighbor interpolation). External upscaler plugins (ESRGAN, Real-ESRGAN, SwinIR, DAT, HAT) implement do_upscale() with their respective deep learning models loaded via spandrel.

Usage

Use Upscaler.upscale() when you need to upscale a PIL Image by a given scale factor using any registered upscaler. The postprocessing pipeline calls this via upscaler.scaler.upscale(image, scale, model_path).

Code Reference

Source Location

• Repository: stable-diffusion-webui
• File: modules/upscaler.py
• Lines: 14-87
• Additional: modules/upscaler_utils.py lines 51-88 (tiled upscaling)

Signature

# Main upscale method (modules/upscaler.py:L54-76)
class Upscaler:
    def upscale(self, img: PIL.Image, scale, selected_model: str = None):
        ...

    @abstractmethod
    def do_upscale(self, img: PIL.Image, selected_model: str):
        return img

# Tiled upscaling utility (modules/upscaler_utils.py:L51-88)
def upscale_with_model(
    model: Callable[[torch.Tensor], torch.Tensor],
    img: Image.Image,
    *,
    tile_size: int,
    tile_overlap: int = 0,
    desc="tiled upscale",
) -> Image.Image:
    ...

Import

from modules.upscaler import Upscaler, UpscalerData
from modules.upscaler_utils import upscale_with_model, upscale_pil_patch

I/O Contract

Inputs (Upscaler.upscale)

Name	Type	Required	Description
img	PIL.Image	Yes	The input image to upscale
scale	float	Yes	The target scale factor (e.g., 2.0 for 2x, 4.0 for 4x). Target dimensions are aligned to multiples of 8.
selected_model	str	No	Path or identifier of the specific model file to use for upscaling (default: None, uses the upscaler's default model)

Inputs (upscale_with_model)

Name	Type	Required	Description
model	Callable[[torch.Tensor], torch.Tensor]	Yes	The neural network model callable that processes a BCHW tensor
img	PIL.Image	Yes	The input image to upscale
tile_size	int	Yes	Size of each tile in pixels. If <= 0, the full image is processed without tiling.
tile_overlap	int	No	Number of pixels of overlap between adjacent tiles (default: 0)
desc	str	No	Description string for the progress bar (default: "tiled upscale")

Outputs

Name	Type	Description
return	PIL.Image	The upscaled image at the target resolution (exact dimensions from scale factor, aligned to multiples of 8)

Usage Examples

Basic Usage

from modules import shared
from PIL import Image

# Find an upscaler by name
upscaler_data = next(x for x in shared.sd_upscalers if x.name == "R-ESRGAN 4x+")

# Upscale an image by 4x
img = Image.open("input.png")
upscaled = upscaler_data.scaler.upscale(img, scale=4.0, selected_model=upscaler_data.data_path)
upscaled.save("output.png")

Using Tiled Upscaling Directly

from modules.upscaler_utils import upscale_with_model
from PIL import Image

# Upscale with tiling for VRAM management
result = upscale_with_model(
    model=loaded_model,
    img=Image.open("input.png"),
    tile_size=512,
    tile_overlap=32,
    desc="Upscaling with ESRGAN",
)

Related Pages

Implements Principle

• Principle:AUTOMATIC1111_Stable_diffusion_webui_Image_upscaling

Requires Environment

• Environment:AUTOMATIC1111_Stable_diffusion_webui_GPU_Compute_Backend