---

name: inference description: "Use GFPGAN for face-restoration inference, model-version selection, aligned crop handling, GFPGANer API calls, and inference troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

GFPGAN Inference

Use this sub-skill when a user wants to restore faces from a photo, folder, aligned crop, or application pipeline with GFPGAN.

Use This For

• Running GFPGAN on one image or a directory of images.
• Choosing between versions 1, 1.2, 1.3, 1.4, and RestoreFormer.
• Deciding whether to use --aligned, --only-center-face, --suffix, --ext, --weight, or background upsampling.
• Calling gfpgan.GFPGANer from Python code.
• Explaining output folders such as cropped faces, restored faces, comparison images, and pasted-back restored images.
• Debugging missing checkpoints, missing optional Real-ESRGAN, no face detections, CPU/GPU surprises, OpenCV image failures, or output naming confusion.

Route Elsewhere

• Training configs, FFHQ data, dataset degradation, landmark files, and checkpoint conversion: use ../training/.
• Package-wide install/CUDA import problems: start with ../../references/installation.md and ../../references/troubleshooting.md.
• Cog/Replicate/Gradio deployment: use this sub-skill for the GFPGAN model call, but treat deployment-specific packaging as a separate application task.

Quick Start

Prefer the bundled helper when you need a safe, explicit inference run that does not auto-download weights by default:

python sub-skills/inference/scripts/run_inference.py \
  --input /path/to/input.jpg \
  --output outputs/gfpgan \
  --model-path /path/to/GFPGANv1.4.pth \
  --version 1.4 \
  --upscale 2 \
  --no-bg-upsampler

For already aligned face crops:

python sub-skills/inference/scripts/run_inference.py \
  --input /path/to/aligned-crops \
  --output outputs/gfpgan-crops \
  --model-path /path/to/GFPGANv1.3.pth \
  --version 1.3 \
  --aligned \
  --ext png

References

• references/workflows.md: end-to-end CLI and API recipes, output layout, and validation steps.
• references/cli-reference.md: verified command-line flags, defaults, and model path behavior.
• references/model-selection.md: version/architecture tradeoffs, checkpoint filenames, and background upsampler decisions.
• references/troubleshooting.md: inference-specific failures and recovery actions.

Bundled Scripts

• scripts/run_inference.py: safe GFPGAN inference wrapper with explicit checkpoint handling and no network download unless requested.
• scripts/check_env.py: inference-focused import/signature/backend check that avoids loading model weights.

Decision Notes

• Use version=1.4 or 1.3 for most modern clean inference requests unless the user specifically needs 1.2, the original paper model 1, or RestoreFormer.
• Use --aligned only when inputs are already aligned face crops; for whole photos, leave it off so GFPGAN detects and pastes faces back.
• Use --no-bg-upsampler when the user only needs face restoration or is on CPU. Add Real-ESRGAN only when non-face background upsampling is a real requirement.
• Do not imply that a missing checkpoint can be silently ignored. Tell the user which checkpoint file/version is needed.