WAIT — Stale — last commit 2y ago

• 11 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

GFPGAN is a practical face restoration algorithm that uses generative priors and identity-preserving techniques to enhance and restore degraded facial images in the wild. It leverages StyleGAN2 as a backbone generator combined with a detection-based restoration pipeline to handle real-world corrupted faces at scale, supporting both cropped faces and whole image processing via built-in face detection. Modular architecture: gfpgan/archs/ contains model implementations (gfpganv1_arch.py, stylegan2_clean_arch.py, restoreformer_arch.py), gfpgan/models/ has training logic (gfpgan_model.py), gfpgan/data/ handles datasets (ffhq_degradation_dataset.py), while inference_gfpgan.py is the standalone entry point. Training is driven by YAML configs in options/ (e.g., train_gfpgan_v1.yml) parsed by gfpgan/train.py.

Computer vision researchers, image restoration engineers, and application developers building face enhancement features who need production-grade face restoration that handles real-world degradation (blur, noise, low resolution) without requiring extensive manual preprocessing.

Production-ready and actively maintained. The repo has significant GitHub engagement (evident from download badges and multiple CI workflows), official PyPI package distribution (gfpgan on PyPI), and comprehensive CI/CD setup with pylint and publish-pip workflows. Recent updates include Replicate and Hugging Face Gradio demos, indicating active development beyond the initial paper release.

Low risk for production use but some constraints: dependency on basicsr>=1.4.2 and facexlib>=0.2.5 (both maintained by same team but adds supply chain dependency), large model weights not versioned in git (stored in experiments/pretrained_models/), and CUDA extension support means CPU-only inference is limited. Single organization (TencentARC) maintains core; community contributions exist but core dev appears centralized.

Active feature development: recent updates include multiple architecture variants (bilinear versions, RestoreFormer support), demo infrastructure (cog.yaml for Replicate, cog_predict.py), and improved inference scripts. CI workflows are in place for linting and PyPI publishing, suggesting ongoing maintenance and release cadence.

git clone https://github.com/TencentARC/GFPGAN.git
cd GFPGAN
pip install -e .
python inference_gfpgan.py -i inputs/whole_imgs/00.jpg -o results -v 1.3 -s 2

Note: First run will auto-download pretrained weights (~350MB) to experiments/pretrained_models/.

Daily commands: For inference on images: python inference_gfpgan.py -i <image_path> -o <output_dir> -v 1.3 -s 2 (v1.3 is model version, s is upsampling factor). For training: python gfpgan/train.py -opt options/train_gfpgan_v1.yml. Cog containerized demo available via cog predict -i image=@input.jpg.

• inference_gfpgan.py — Main entry point for face restoration inference—every developer must understand how to run the model end-to-end.
• gfpgan/models/gfpgan_model.py — Core model definition and training logic; essential for understanding the training pipeline and model architecture.
• gfpgan/archs/gfpganv1_arch.py — Primary GFPGAN v1 architecture implementation; defines the neural network structure used for face restoration.
• gfpgan/utils.py — Shared utility functions for face detection, cropping, and image processing used across the codebase.
• gfpgan/data/ffhq_degradation_dataset.py — Dataset handling for FFHQ with degradation simulation; critical for understanding the training data pipeline.
• requirements.txt — Dependencies including basicsr and facexlib; essential for understanding external frameworks and their roles.
• gfpgan/train.py — Training loop orchestration; shows how the model, dataset, and loss functions integrate during training.

Add a New Restoration Architecture

1. Create a new architecture file in gfpgan/archs/ following the naming convention (e.g., gfpganv2_arch.py) with a nn.Module subclass (gfpgan/archs/gfpganv2_arch.py)
2. Register the new architecture in the init.py file so it can be imported (gfpgan/archs/__init__.py)
3. Create a test file to validate forward pass and output tensor shapes (tests/test_gfpganv2_arch.py)
4. Update gfpgan/models/gfpgan_model.py to support instantiation of the new architecture by adding a condition in the model initialization (gfpgan/models/gfpgan_model.py)
5. Create a new training config YAML file in options/ with the new architecture name and hyperparameters (options/train_gfpganv2.yml)

Add a New Degradation Type to Training Data

1. Open the degradation dataset class and add a new degradation function (e.g., motion blur, rain, snow) (gfpgan/data/ffhq_degradation_dataset.py)
2. Update the degradation pipeline in the getitem method to randomly apply the new degradation with a certain probability (gfpgan/data/ffhq_degradation_dataset.py)
3. Add a test case to verify the new degradation is applied and output remains valid (tests/test_ffhq_degradation_dataset.py)
4. Update the training config YAML file to expose any new hyperparameters (e.g., degradation probability, intensity) (options/train_gfpgan_v1.yml)

Deploy Face Restoration as a Service

1. Create a wrapper around inference_gfpgan.py that loads the model once at startup and processes requests (inference_gfpgan.py)
2. Use the Cog configuration to containerize the service for cloud deployment (Replicate, RunwayML, etc.) (cog.yaml)
3. Implement the predict function in cog_predict.py to accept image inputs and return restored face URLs or base64 data (cog_predict.py)
4. Verify the model weights are downloaded and cached by adding a download step in the Cog config or predict function (gfpgan/weights/README.md)

Fine-tune GFPGAN on Custom Face Domain

1. Prepare paired or unpaired high-quality/degraded face images and organize them following FFHQ LMDB or folder structure (gfpgan/data/ffhq_degradation_dataset.py)
2. Create a new training config YAML by copying options/train_gfpgan_v1.yml and updating paths, learning rates, and loss weights (options/train_gfpgan_custom.yml)
3. Run the training script with the new config to fine-tune the pretrained model on your custom domain (gfpgan/train.py)
4. Evaluate the fine-tuned model by running inference_gfpgan.py with the new checkpoint path to validate quality improvements (inference_gfpgan.py)

• PyTorch — Deep learning framework; enables GPU-accelerated neural network training and inference for real-time face restoration
• basicsr (Basic Image Super-Resolution) — Provides foundational SR/restoration utilities, loss functions (L1, Perceptual, GAN), and training infrastructure
• facexlib — Face detection, alignment, and parsing; critical for locating and preprocessing faces before restoration
• StyleGAN2 — Generative prior for realistic face synthesis; provides high-level semantic guidance during restoration
• LMDB — Fast on-disk storage for large-scale image datasets (FFHQ); enables efficient random-access training data loading
• OpenCV — Image I/O, color space conversion, and pre/post-processing operations for faces and full images

• Two-stage restoration (encoder + two decoders) with StyleGAN2 prior

  • Why: Balances realism (StyleGAN2 guides output) with detail recovery (UNet decoder) and identity preservation (ArcFace loss)
  • Consequence: Increased model size and inference latency compared to single-decoder designs; requires three forward passes per face

• Synthetic degradation during training (blur, noise, compression, downsampling)

  • Why: Avoids expensive dataset annotation; enables training on unpaired data (FFHQ alone)
  • Consequence: May not generalize perfectly to real-world degradation types; requires careful degradation distribution tuning

• Face-level restoration (

  • Why: undefined
  • Consequence: undefined

Model weights (~350MB per version) auto-download on first inference to experiments/pretrained_models/ but require internet access and disk space; no explicit cache invalidation. Face detection via facexlib may silently fail on edge cases (very small faces, extreme angles) without clear error messages. YAML config parsing via gfpgan/train.py expects strict structure matching options/train_gfpgan_v1.yml—missing keys cause cryptic errors. CUDA extensions in original StyleGAN2 version can fail on some GPU/driver combos; use stylegan2_clean_arch.py as fallback. Degradation dataset assumes FFHQ-like face crops; using non-face images during training may cause dimension mismatches.

• Generative Prior — GFPGAN leverages StyleGAN2 as a pre-trained generative prior to implicitly constrain restoration outputs to natural-looking faces, which is essential to understanding why GFPGAN produces sharper results than pixel-space L1 optimization
• Identity-Preserving Loss — GFPGAN uses ArcFace embeddings (via arcface_arch.py) to ensure restored faces preserve identity features of the original degraded input—a key differentiator from general image restoration that this codebase implements
• Blind Face Restoration — GFPGAN is a blind restoration method (doesn't know degradation type beforehand) using a unified architecture; the degradation dataset synthesis in ffhq_degradation_dataset.py mimics this real-world scenario
• Adversarial Loss — GFPGAN uses GAN losses (generator vs discriminator) as a core training signal in gfpgan_model.py to achieve perceptually pleasing outputs; understanding GAN dynamics is critical for debugging training instability
• Perceptual Loss — GFPGAN combines pixel-space (L1), feature-space (perceptual), and identity losses in gfpgan_model.py; perceptual loss from pre-trained CNNs captures human-relevant image quality better than MSE
• Coarse-to-Fine Restoration — The multi-scale architecture in gfpganv1_arch.py uses U-Net style skip connections to progressively refine face quality from coarse structure to fine details, a pattern visible in the network design
• LMDB Dataset Format — Training uses LMDB (Lightning Memory-Mapped Database) for fast random access to millions of training images; the basicsr framework abstracts this but understanding it explains I/O efficiency in large-scale training

• xinntao/Real-ESRGAN — Companion project from same author handling general image super-resolution; shares BasicSR framework and provides baseline upsampling for GFPGAN pipeline
• chaofengc/Face-Restoration-Benchmark — Comprehensive evaluation suite for face restoration methods including GFPGAN; useful for benchmarking against other restoration approaches
• TencentARC/BasicSR — Underlying training framework used by GFPGAN (imports basicsr for model training, logging, config parsing); core dependency for extending training pipeline
• xinntao/facexlib — Face detection and alignment library used by GFPGAN for preprocessing; powers the face crop detection in inference_gfpgan.py
• NVlabs/stylegan2 — Original StyleGAN2 implementation that GFPGAN adapts as its generator backbone; referenced in gfpganv1_arch.py

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for inference_gfpgan.py with multiple model architectures

The repo has multiple architecture variants (gfpganv1, gfpganv1_clean, bilinear, restoreformer) in gfpgan/archs/ but only basic architecture unit tests exist in tests/. The inference_gfpgan.py script lacks comprehensive integration tests verifying end-to-end face restoration across different model types and input formats. This is critical for catching regressions when updating core inference logic.

• [ ] Create tests/test_inference_gfpgan.py with test fixtures for each architecture in gfpgan/archs/
• [ ] Add test cases for both cropped face inputs (inputs/cropped_faces/) and whole image inputs (inputs/whole_imgs/)
• [ ] Verify output dimensions and tensor properties match expected restoration results
• [ ] Test with and without GPU availability to ensure device handling is robust

Add GitHub Actions workflow to test dependency compatibility across Python versions

The repo has publish-pip.yml, pylint.yml, and release.yml workflows, but no matrix testing for Python 3.7-3.11 compatibility. Given dependencies like torch>=1.7 and torchvision span multiple versions, automated testing across Python versions would catch compatibility regressions early. This is especially important since setup.py doesn't specify python_requires.

• [ ] Create .github/workflows/test-matrix.yml with Python 3.8, 3.9, 3.10, 3.11 matrix
• [ ] Include jobs testing both CPU and GPU-enabled environments (if feasible)
• [ ] Run pytest on tests/ directory for each Python version
• [ ] Update README.md with tested Python version guarantees

Add unit tests for gfpgan/utils.py with comprehensive coverage

The utils.py module is imported by gfpgan/init.py and used across the codebase, but there are no corresponding tests in tests/. Common utility functions like face detection, image loading, and preprocessing are typically fragile points. Currently only specific architecture tests exist (test_gfpgan_arch.py, test_ffhq_degradation_dataset.py).

• [ ] Create tests/test_utils.py targeting all public functions exported from gfpgan/utils.py
• [ ] Add fixtures using test images from inputs/ and tests/data/ directories
• [ ] Test edge cases: corrupted images, extreme dimensions, missing files, invalid tensor inputs
• [ ] Verify integration with facexlib and basicsr utilities used in the utils module

• Add unit tests for gfpgan/data/ffhq_degradation_dataset.py: currently no test coverage for degradation pipeline—write tests validating that blur/noise/compression kernels produce expected output shapes and value ranges
• Extend inference_gfpgan.py with batch processing support: currently processes images one-at-a-time; add --batch-size flag and vectorized face detection/restoration to speed up processing of image folders (10-100x speedup possible)
• Document model architecture decisions in docstrings for gfpgan/archs/gfpganv1_arch.py: explain why identity-preserving branch is separate, what each loss component does, and how it differs from prior GAN-based restoration methods

The GFPGAN codebase demonstrates reasonable security practices as an ML research project, but has moderate vulnerabilities. Primary concerns include: (1) loose dependency version constraints allowing vulnerable packages, (2) unsafe YAML deserialization risk from pyyaml usage, (3) insufficient input validation in inference pipeline, and (4) test data containing facial images in the repository. The project lacks explicit

• Medium · Unspecified Dependency Versions — requirements.txt. The requirements.txt file uses loose version constraints (e.g., 'basicsr>=1.4.2', 'torch>=1.7'). This allows installation of newer versions that may contain vulnerabilities. Without pinned versions, different installations may have inconsistent and potentially insecure dependencies. Fix: Pin all dependency versions to specific release tags (e.g., 'torch==1.13.1' instead of 'torch>=1.7'). Use a lock file (e.g., pip-compile, poetry.lock) to ensure reproducible and verified installations.
• Medium · PyYAML Deserialization Risk — gfpgan/train.py, options/, requirements.txt. The dependency 'pyyaml' is used (visible in requirements.txt and .pre-commit-config.yaml). PyYAML with unsafe_load() can deserialize arbitrary Python objects, leading to code execution. Configuration files in 'options/' and 'tests/data/' parse YAML without visible safety checks in provided context. Fix: Use yaml.safe_load() instead of yaml.load() or yaml.unsafe_load(). Validate all YAML configuration files against a schema. Implement input sanitization for user-provided YAML files.
• Medium · Insufficient Input Validation in Inference Script — inference_gfpgan.py. The inference_gfpgan.py script processes input images from 'inputs/' directory. Without visible input validation, malformed image files or path traversal attacks could be exploited. Fix: Implement strict input validation for file paths, image dimensions, and file formats. Use os.path.abspath() and verify files are within allowed directories. Validate image headers before processing.
• Low · Missing MANIFEST.in Security Directives — MANIFEST.in. MANIFEST.in file exists but its contents are not visible. This could lead to unintended inclusion/exclusion of sensitive files in distribution packages. Fix: Explicitly exclude sensitive files (.env, *.key, test data with PII, credentials) from MANIFEST.in. Verify distribution packages don't contain unnecessary sensitive data.
• Low · Test Data in Repository — tests/data/. Test data including images and LMDB databases are stored in the repository (tests/data/). This could expose facial images or training data if the repo is publicly accessible. Fix: Move large/sensitive test data to a separate data repository or use fixtures generated at runtime. If test data contains real images, ensure proper consent and compliance with privacy regulations (GDPR, CCPA).
• Low · Missing Security Headers in GitHub Actions — .github/workflows/. GitHub Actions workflows (.github/workflows/) may be missing security contexts and OIDC token restrictions, potentially exposing CI/CD pipeline to supply chain attacks. Fix: Add 'permissions: read-only' at workflow level. Use OIDC for package publishing instead of static tokens. Implement branch protection rules and require signed commits.
• Low · Cog Configuration Exposure — cog.yaml, cog_predict.py. cog.yaml and cog_predict.py files suggest containerized deployment. If deployed to Cog platform, ensure sensitive model paths and parameters aren't exposed. Fix: Use environment variables for sensitive configurations. Implement proper authentication/authorization for model endpoints. Restrict public API access if dealing with sensitive facial data.
• Low · Outdated PyTorch Constraint — requirements.txt. Minimum PyTorch version specified as '>=1.7' is from 2020 and may contain known vulnerabilities. Fix: Update minimum PyTorch version to at least 2.0+. Test compatibility and update requirements accordingly. Monitor PyTorch security advisories.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/TencentARC/GFPGAN shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live TencentARC/GFPGAN repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TencentARC/GFPGAN.

What it runs against: a local clone of TencentARC/GFPGAN — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in TencentARC/GFPGAN | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 681 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TencentARC/GFPGAN. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TencentARC/GFPGAN.git
#   cd GFPGAN
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of TencentARC/GFPGAN and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TencentARC/GFPGAN(\\.git)?\\b" \\
  && ok "origin remote is TencentARC/GFPGAN" \\
  || miss "origin remote is not TencentARC/GFPGAN (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "inference_gfpgan.py" \\
  && ok "inference_gfpgan.py" \\
  || miss "missing critical file: inference_gfpgan.py"
test -f "gfpgan/models/gfpgan_model.py" \\
  && ok "gfpgan/models/gfpgan_model.py" \\
  || miss "missing critical file: gfpgan/models/gfpgan_model.py"
test -f "gfpgan/archs/gfpganv1_arch.py" \\
  && ok "gfpgan/archs/gfpganv1_arch.py" \\
  || miss "missing critical file: gfpgan/archs/gfpganv1_arch.py"
test -f "gfpgan/utils.py" \\
  && ok "gfpgan/utils.py" \\
  || miss "missing critical file: gfpgan/utils.py"
test -f "gfpgan/data/ffhq_degradation_dataset.py" \\
  && ok "gfpgan/data/ffhq_degradation_dataset.py" \\
  || miss "missing critical file: gfpgan/data/ffhq_degradation_dataset.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 681 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~651d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/TencentARC/GFPGAN"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.