# tencentarc/gfpgan architecture

> Architecture diagram of the GitHub repository tencentarc/gfpgan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencentarc/gfpgan
- Repository: https://github.com/tencentarc/gfpgan

## Overview

GFPGAN is a practical blind face-restoration package. Its main user workflow reads images, selects and loads a restoration model, detects and aligns faces, restores each crop, optionally enhances the background, then pastes faces back and saves results. The repository also provides a BasicSR-based training path and multiple model families, including RestoreFormer and bilinear variants. The source excerpts show inference and restoration-helper calls; training internals and several architecture implementations were not sampled, so their detailed runtime connections are omitted.

Main entry points: [`gfpgan/utils.py`](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/utils.py) (GFPGANer), [`inference_gfpgan.py`](https://github.com/tencentarc/gfpgan/blob/master/inference_gfpgan.py) (Inference CLI), [`gfpgan/archs/gfpgan_bilinear_arch.py`](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpgan_bilinear_arch.py) (Bilinear GFPGAN), [`gfpgan/train.py`](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/train.py) (Training entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Inference workflow"]
  node_inference["Inference CLI"]
  node_restorer["GFPGANer<br/>[utils.py]"]
  node_outputs["Restoration outputs"]
end

subgraph group_restoration["Face restoration"]
  node_facehelper["Face detection and alignment"]
  node_background["Real-ESRGAN upsampler"]
end

subgraph group_models["Model architectures"]
  node_clean["Clean GFPGAN"]
  node_original["Original GFPGAN<br/>[gfpganv1_arch.py]"]
  node_bilinear["Bilinear GFPGAN"]
  node_restoreformer["RestoreFormer"]
  node_stylegan_clean["Clean StyleGAN2"]
  node_stylegan_bilinear["Bilinear StyleGAN2"]
end

subgraph group_training["Training"]
  node_dataset["Degradation dataset"]
  node_train_model["GFPGAN training model<br/>[gfpgan_model.py]"]
  node_train_entry["Training entry point<br/>[train.py]"]
end

node_user(("Image user"))

node_user -->|"runs"| node_inference
node_inference -->|"calls"| node_restorer
node_restorer -->|"detects and aligns"| node_facehelper
node_restorer -->|"selects model"| node_clean
node_restorer -->|"selects model"| node_original
node_restorer -->|"selects model"| node_bilinear
node_restorer -->|"selects model"| node_restoreformer
node_restorer -->|"upsamples background"| node_background
node_clean -->|"uses generator"| node_stylegan_clean
node_bilinear -->|"reuses architecture"| node_original
node_bilinear -->|"uses generator"| node_stylegan_bilinear
node_inference -.->|"configures optionally"| node_background
node_inference -->|"writes images"| node_outputs
node_train_entry -->|"registers datasets"| node_dataset
node_train_entry -->|"registers models"| node_train_model

click node_inference "https://github.com/tencentarc/gfpgan/blob/master/inference_gfpgan.py"
click node_restorer "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/utils.py"
click node_outputs "https://github.com/tencentarc/gfpgan/blob/master/inference_gfpgan.py"
click node_clean "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpganv1_clean_arch.py"
click node_original "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpganv1_arch.py"
click node_bilinear "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpgan_bilinear_arch.py"
click node_restoreformer "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/restoreformer_arch.py"
click node_stylegan_clean "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/stylegan2_clean_arch.py"
click node_stylegan_bilinear "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/stylegan2_bilinear_arch.py"
click node_dataset "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/data/ffhq_degradation_dataset.py"
click node_train_model "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/models/gfpgan_model.py"
click node_train_entry "https://github.com/tencentarc/gfpgan/blob/master/gfpgan/train.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inference,node_restorer,node_outputs,node_user toneBlue
class node_facehelper,node_background toneAmber
class node_clean,node_original,node_bilinear,node_restoreformer,node_stylegan_clean,node_stylegan_bilinear toneMint
class node_dataset,node_train_model,node_train_entry toneRose
```

## Components

### Inference workflow

- [Inference CLI](https://github.com/tencentarc/gfpgan/blob/master/inference_gfpgan.py): `inference_gfpgan.py`
- [GFPGANer](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/utils.py): `gfpgan/utils.py`
- [Restoration outputs](https://github.com/tencentarc/gfpgan/blob/master/inference_gfpgan.py): `inference_gfpgan.py`

### Face restoration

- **Face detection and alignment**
- **Real-ESRGAN upsampler**

### Model architectures

- [Clean GFPGAN](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpganv1_clean_arch.py): `gfpgan/archs/gfpganv1_clean_arch.py`
- [Original GFPGAN](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpganv1_arch.py): `gfpgan/archs/gfpganv1_arch.py`
- [Bilinear GFPGAN](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/gfpgan_bilinear_arch.py): `gfpgan/archs/gfpgan_bilinear_arch.py`
- [RestoreFormer](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/restoreformer_arch.py): `gfpgan/archs/restoreformer_arch.py`
- [Clean StyleGAN2](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/stylegan2_clean_arch.py): `gfpgan/archs/stylegan2_clean_arch.py`
- [Bilinear StyleGAN2](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/archs/stylegan2_bilinear_arch.py): `gfpgan/archs/stylegan2_bilinear_arch.py`

### Training

- [Degradation dataset](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/data/ffhq_degradation_dataset.py): `gfpgan/data/ffhq_degradation_dataset.py`
- [GFPGAN training model](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/models/gfpgan_model.py): `gfpgan/models/gfpgan_model.py`
- [Training entry point](https://github.com/tencentarc/gfpgan/blob/master/gfpgan/train.py): `gfpgan/train.py`

### Other components

- **Image user**

## Connections

- Image user → Inference CLI: runs (evidence: `README.md`)
- Inference CLI → GFPGANer: calls (evidence: `inference_gfpgan.py`)
- GFPGANer → Face detection and alignment: detects and aligns (evidence: `gfpgan/utils.py`)
- GFPGANer → Clean GFPGAN: selects model (evidence: `gfpgan/utils.py`)
- GFPGANer → Original GFPGAN: selects model (evidence: `gfpgan/utils.py`)
- GFPGANer → Bilinear GFPGAN: selects model (evidence: `gfpgan/utils.py`)
- GFPGANer → RestoreFormer: selects model (evidence: `gfpgan/utils.py`)
- GFPGANer → Real-ESRGAN upsampler: upsamples background (evidence: `gfpgan/utils.py`)
- Clean GFPGAN → Clean StyleGAN2: uses generator (evidence: `gfpgan/archs/gfpganv1_clean_arch.py`)
- Bilinear GFPGAN → Original GFPGAN: reuses architecture (evidence: `gfpgan/archs/gfpgan_bilinear_arch.py`)
- Bilinear GFPGAN → Bilinear StyleGAN2: uses generator (evidence: `gfpgan/archs/gfpgan_bilinear_arch.py`)
- Inference CLI → Real-ESRGAN upsampler: configures optionally (evidence: `inference_gfpgan.py`)
- Inference CLI → Restoration outputs: writes images (evidence: `inference_gfpgan.py`)
- Training entry point → Degradation dataset: registers datasets (evidence: `gfpgan/train.py`)
- Training entry point → GFPGAN training model: registers models (evidence: `gfpgan/train.py`)
