Implementation:AUTOMATIC1111 Stable diffusion webui Restore faces

Knowledge Sources	stable-diffusion-webui
Domains	Face Restoration, Deep Learning, Computer Vision
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for restoring degraded faces in images by dispatching to the user-configured face restoration backend (CodeFormer or GFPGAN) provided by stable-diffusion-webui.

Description

The restore_faces() function in modules/face_restoration.py is a thin dispatcher that selects the active face restoration model from a global registry (shared.face_restorers) based on the user's setting in shared.opts.face_restoration_model, then delegates to that model's restore() method.

This is a wrapper implementation that wraps two underlying restoration backends:

• CodeFormer (modules/codeformer_model.py): Loads the CodeFormer model via spandrel, invokes it with a configurable fidelity weight parameter (code_former_weight, default 0.5), and uses the CommonFaceRestoration base class from face_restoration_utils.py to handle face detection (RetinaFace), alignment, and pasting via facexlib's FaceRestoreHelper.
• GFPGAN (modules/gfpgan_model.py): Loads the GFPGAN v1.4 model via spandrel and invokes it through the same CommonFaceRestoration infrastructure.

Both backends follow the same pattern: detect faces with RetinaFace, crop and align each face to 512x512, normalize to [-1, 1] range, run the restoration network, convert back to [0, 255] uint8 BGR, and paste into the original image using inverse affine transforms. Model weights are optionally unloaded to CPU after inference when face_restoration_unload is enabled.

Usage

Use restore_faces() as the primary entry point for face restoration in postprocessing pipelines. It is called by the postprocessing scripts and can be invoked directly from any code that has a NumPy BGR image array.

Code Reference

Source Location

• Repository: stable-diffusion-webui
• File: modules/face_restoration.py
• Lines: 12-19
• Additional: modules/codeformer_model.py lines 25-55, modules/gfpgan_model.py lines 23-51, modules/face_restoration_utils.py lines 58-110

Signature

# Dispatcher (modules/face_restoration.py:L12-19)
def restore_faces(np_image):
    ...

# Base class (modules/face_restoration.py:L4-9)
class FaceRestoration:
    def name(self):
        return "None"
    def restore(self, np_image):
        return np_image

# CodeFormer restore (modules/codeformer_model.py:L47-55)
class FaceRestorerCodeFormer(CommonFaceRestoration):
    def restore(self, np_image, w: float | None = None):
        ...

# GFPGAN restore (modules/gfpgan_model.py:L46-51)
class FaceRestorerGFPGAN(CommonFaceRestoration):
    def restore(self, np_image):
        ...

Import

from modules.face_restoration import restore_faces

I/O Contract

Inputs

Name	Type	Required	Description
np_image	np.ndarray	Yes	Input image as a NumPy array in BGR format with shape (H, W, 3) and dtype uint8

Outputs

Name	Type	Description
return	np.ndarray	The image with all detected faces restored, same format as input (BGR uint8 NumPy array). Returns the original image unchanged if no face restorer is configured.

Usage Examples

Basic Usage

import numpy as np
from PIL import Image
from modules.face_restoration import restore_faces

# Convert PIL Image to NumPy BGR array
pil_image = Image.open("portrait.png")
np_image = np.array(pil_image)[:, :, ::-1]  # RGB to BGR

# Restore faces using the currently configured model
restored = restore_faces(np_image)

# Convert back to PIL Image
restored_pil = Image.fromarray(restored[:, :, ::-1])  # BGR to RGB
restored_pil.save("restored_portrait.png")

Using CodeFormer Directly with Custom Weight

from modules.codeformer_model import codeformer

# Restore with a specific fidelity weight (0.0 = max quality, 1.0 = max fidelity)
if codeformer is not None:
    restored = codeformer.restore(np_image, w=0.7)

Related Pages

Implements Principle

• Principle:AUTOMATIC1111_Stable_diffusion_webui_Face_restoration