Implementation:AUTOMATIC1111 Stable diffusion webui Save image

Knowledge Sources	stable-diffusion-webui
Domains	Image Processing, Metadata Management, File Formats, Data Persistence
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for saving images to disk with embedded generation metadata, automatic filename generation, and format-specific metadata handling provided by stable-diffusion-webui.

Description

save_image() in modules/images.py is the primary function for persisting generated and postprocessed images. It handles the complete save workflow:

1. Filename generation: Uses a FilenameGenerator that supports configurable patterns with tokens like [seed], [prompt_words], [date], [model_name], [sampler], and many others. Sequence numbers are appended to ensure uniqueness.
2. Directory management: Optionally creates subdirectories based on filename patterns (e.g., organizing by prompt or date). Creates directories as needed with os.makedirs.
3. Format auto-switching: If the image dimensions exceed the maximum supported by the target format (65535 for JPEG, 16383 for WebP), the format is automatically switched to PNG.
4. Metadata embedding: Delegates to save_image_with_geninfo() which handles format-specific metadata:
   • PNG: Generation info stored in tEXt chunks via PngImagePlugin.PngInfo
   • JPEG: Generation info stored in EXIF UserComment via piexif
   • WebP: Saved with configurable quality and lossless mode; EXIF metadata inserted via piexif
   • AVIF: EXIF metadata embedded directly during save
   • GIF: Generation info stored in comment extension block
5. Atomic writes: Images are written to a .tmp file first, then atomically renamed to the final path using os.replace().
6. Callbacks: Fires before_image_saved_callback and image_saved_callback script callbacks, allowing extensions to intercept or modify the save operation.
7. 4chan export: Optionally creates a downscaled JPEG copy when the image exceeds configured size thresholds (file size or pixel dimensions).
8. Text file companion: Optionally writes a .txt file alongside the image containing the generation info in plain text.

Usage

Use save_image() whenever you need to persist an image with generation metadata. It is called by the postprocessing pipeline, the txt2img/img2img generation pipeline, and any code that needs to save images with provenance information.

Code Reference

Source Location

• Repository: stable-diffusion-webui
• File: modules/images.py
• Lines: 624-767

Signature

def save_image(
    image,
    path,
    basename,
    seed=None,
    prompt=None,
    extension='png',
    info=None,
    short_filename=False,
    no_prompt=False,
    grid=False,
    pnginfo_section_name='parameters',
    p=None,
    existing_info=None,
    forced_filename=None,
    suffix="",
    save_to_dirs=None,
):

Import

from modules.images import save_image

I/O Contract

Inputs

Name	Type	Required	Description
image	PIL.Image	Yes	The image to save
path	str	Yes	Base output directory. If save_to_dirs is True, a subdirectory will be created within this path.
basename	str	Yes	Base filename prefix used in the filename pattern. If empty, only the sequence number and decorations are used.
seed	int	No	The generation seed, used in filename patterns and metadata (default: None)
prompt	str	No	The generation prompt, used in filename patterns (default: None)
extension	str	No	Image format extension without dot: 'png', 'jpg', 'jpeg', 'webp', 'avif', 'gif' (default: 'png')
info	str	No	Generation info text to embed as metadata in the image file (default: None)
short_filename	bool	No	If True, uses minimal filename decoration (default: False)
no_prompt	bool	No	If True, suppresses automatic save_to_dirs behavior (default: False)
grid	bool	No	If True, uses grid-specific save_to_dirs and filename pattern settings (default: False)
pnginfo_section_name	str	No	Key name under which info is stored in PNG metadata (default: 'parameters')
p	StableDiffusionProcessing	No	The processing object, used for filename pattern token resolution (default: None)
existing_info	dict	No	Additional PNG info dictionary entries to include alongside the generation info (default: None)
forced_filename	str	No	If specified, overrides all filename pattern logic and uses this exact name (without extension) (default: None)
suffix	str	No	String appended to the filename after the pattern-generated portion (default: "")
save_to_dirs	bool	No	Whether to create a subdirectory within path. If None, determined by options and the grid flag (default: None)

Outputs

Name	Type	Description
fullfn	str	The full filesystem path of the saved image file
txt_fullfn	str or None	The full path of the companion .txt file if save_txt is enabled and info is not None, otherwise None

Usage Examples

Basic Usage

from modules.images import save_image
from PIL import Image

image = Image.open("generated.png")
fullfn, txt_fullfn = save_image(
    image=image,
    path="/output/extras",
    basename="",
    seed=12345,
    prompt="a beautiful landscape",
    extension="png",
    info="Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345",
)
print(f"Saved to: {fullfn}")

Saving with Forced Filename and Existing Info

from modules.images import save_image

existing_pnginfo = {"parameters": "original generation info"}
fullfn, txt_fullfn = save_image(
    image=processed_image,
    path="/output/extras",
    basename="batch",
    extension="png",
    info="Postprocess upscale by: 4, Postprocess upscaler: R-ESRGAN 4x+",
    forced_filename="my_upscaled_image",
    existing_info=existing_pnginfo,
    pnginfo_section_name="extras",
)

Saving as JPEG with EXIF Metadata

from modules.images import save_image

fullfn, txt_fullfn = save_image(
    image=image,
    path="/output/extras",
    basename="",
    extension="jpg",
    info="Steps: 20, Sampler: DPM++ 2M, Seed: 42",
    short_filename=True,
    no_prompt=True,
)
# EXIF UserComment will contain the generation info

Related Pages

Implements Principle

• Principle:AUTOMATIC1111_Stable_diffusion_webui_Image_output_saving