---

name: gfpgan description: "Use GFPGAN for face-restoration inference, model-version selection, training/data preparation, checkpoint conversion, and package troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

GFPGAN Repo Skill

Use this repo skill when a user asks about gfpgan, GFPGAN face restoration, blind real-world face enhancement, GFPGAN model versions, the GFPGANer helper API, the inference_gfpgan.py workflow, or GFPGAN training and FFHQ degradation data preparation.

Choose A Route

• sub-skills/inference/: restore faces from images or folders, choose GFPGAN versions (1, 1.2, 1.3, 1.4, RestoreFormer), use aligned crop mode, call the GFPGANer API, interpret output folders, and debug checkpoint/device/image failures.
• sub-skills/training/: prepare FFHQ-style data, configure FFHQDegradationDataset, run BasicSR-backed GFPGAN training, inspect GFPGANModel, generate landmark files, and convert bilinear/original checkpoints into clean checkpoints.

Quick Install Check

GFPGAN is a PyTorch package named gfpgan. A typical runtime environment needs PyTorch, TorchVision, BasicSR, facexlib, OpenCV, LMDB, NumPy, PyYAML, SciPy, and tqdm. For image restoration only, install GFPGAN and its base dependencies first; install realesrgan only when background upsampling is required.

python scripts/check_env.py

Read references/installation.md before changing PyTorch/CUDA wheels, installing optional Real-ESRGAN, or using the original paper model that depends on BasicSR extension/JIT behavior.

Core Facts

• Public package version captured for this skill: 1.3.8.
• The main high-level inference API is gfpgan.utils.GFPGANer(model_path, upscale=2, arch='clean', channel_multiplier=2, bg_upsampler=None, device=None).
• GFPGANer.enhance(img, has_aligned=False, only_center_face=False, paste_back=True, weight=0.5) returns cropped faces, restored faces, and optionally the pasted-back restored image.
• Clean models (1.2, 1.3, 1.4) do not require custom CUDA extensions; the original paper model (1) uses the original architecture and may need BasicSR JIT/extension setup.
• Training is BasicSR-backed, data/checkpoint heavy, and normally GPU/multi-GPU oriented. Do not present full training as a cheap smoke test.

Shared References

• references/installation.md: install variants, dependency roles, CUDA/CPU notes, optional Real-ESRGAN, and original-model extension guidance.
• references/troubleshooting.md: cross-cutting package import, checkpoint, CUDA, OpenCV, BasicSR, and optional dependency failures.
• references/repo-provenance.md: source commit, dirty-state baseline, package version, and evidence paths used to generate this skill.
• references/repo-routing-metadata.json: structured DisCo router metadata used during managed repo-skill import.

Shared Scripts

• scripts/check_env.py: verifies importability, important signatures, package metadata, CUDA visibility, and optional dependency availability without downloading model weights.

Routing Notes

• If the user wants a restored image, output-folder explanation, checkpoint choice, or GFPGANer.enhance, start with sub-skills/inference/.
• If the user wants to train, fine-tune, convert checkpoints, fix an FFHQ data layout, or understand options/train_gfpgan_v1*.yml, start with sub-skills/training/.
• If the user asks for Cog/Replicate/Hugging Face demo deployment, treat it as an external deployment adaptation: use inference knowledge for the model call, but do not run service-specific scripts unless the user explicitly requests that environment.