Install GFPGAN v1.3.8 for AI Face Restoration

Two ways people try AI face restoration with GFPGAN: drop a photo into a hosted demo (Replicate, Hugging Face Spaces) and hope the queue is free, or install GFPGAN v1.3.8 on a machine you control. The demo wins for a one-off curiosity. Local install wins the second you care about private photos, batch folders, offline runs, or wiring restoration into a script. This guide is the local path I actually got working – code v1.3.8, with the V1.4 weights most people want.

Deploy first, paper later. GFPGAN (Tencent ARC) is the blind face restorer from CVPR 2021 – Towards Real-World Blind Face Restoration with Generative Facial Prior (arXiv:2101.04061). It borrows facial detail from a pretrained GAN prior instead of inventing geometry from a mushy scan. You’re here to pin the repo and run inference, not reread the abstract.

System requirements before you touch git

From the official GFPGAN README (v1.3.8 line; tag dated 16 Sep 2022, still the latest code release on GitHub as of this writing):

No numeric VRAM floor appears in the docs – only Python, PyTorch, and optional CUDA. Budget whatever card already runs your other torch jobs. Modern GFPGAN installs skip compiling StyleGAN CUDA extensions; that alone saved me a night of compiler pain on a laptop that only had runtime CUDA.

Official download source

Only trust these:

• Code: https://github.com/TencentARC/GFPGAN (tag/latest release v1.3.8)
• Weights: GitHub Releases assets – GFPGANv1.3.pth and GFPGANv1.4.pth under the v1.3.0 / related release download URLs listed in the README model zoo
• Library-only mirror: pip install gfpgan on PyPI if you don’t need the stock scripts

Skip random SourceForge “mirrors” and mystery zip blogs. Corrupted .pth files fail late with EOF/size errors and waste an hour.

Install GFPGAN v1.3.8 step by step

I use a dedicated environment so basicsr doesn’t fight some other vision project. Commands match the official clean install path.

# 1) Environment
conda create -n gfpgan python=3.10 -y
conda activate gfpgan

# 2) Install PyTorch first (pick the CUDA build from pytorch.org for your box)
# Example CUDA 11.8 wheel - replace with your platform's command
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# 3) Clone exact project
git clone https://github.com/TencentARC/GFPGAN.git
cd GFPGAN
git checkout v1.3.8 # pin the release; master still tracks the 1.3.8 VERSION line

# 4) Core deps (order matters in practice)
pip install basicsr
pip install facexlib
pip install -r requirements.txt
python setup.py develop

# 5) Background upscaler helper (optional)
pip install realesrgan

requirements.txt (master) asks for basicsr>=1.4.2, facexlib>=0.2.5, numpy, opencv-python, pyyaml, scipy, tqdm, yapf, torch/torchvision, and friends. tb-nightly can moan on locked-down networks – install the rest and skip it when you only need inference.

Pro tip: Right after torch installs, freeze versions with pip freeze > gfpgan-lock.txt. Silent torchvision upgrades weeks later are how most “it worked yesterday” breakage starts.

Need only the Python API? pip install gfpgan is enough. For deployment and the stock inference_gfpgan.py entry point, clone + setup.py develop stays clearer.

First-time configuration (weights + folders)

You need three things on disk: weights, an input folder, an output folder. No YAML for basic inference.

mkdir -p experiments/pretrained_models inputs/my_faces results

# V1.3 - README default example path
wget https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth 
 -P experiments/pretrained_models

# V1.4 - same release assets; README calls out slightly more detail + better identity than V1.3
wget https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.4.pth 
 -P experiments/pretrained_models

# Drop test images here (PNG/JPG)
cp /path/to/blurry_portrait.jpg inputs/my_faces/

Windows without wget? Grab the same Releases asset in a browser and drop the .pth under experiments/pretrained_models/. File should be hundreds of MB – a few KB usually means you saved an HTML error page.

Catch on the -v flag: script help still emphasizes 1 | 1.2 | 1.3, while GFPGANv1.4.pth ships as a separate weight. Wrong path or a missing file fails at runtime after a “clean” install – not at pip time.

Verify the install works

# Version pin check
cat VERSION
# expect: 1.3.8

python -c "import gfpgan, basicsr, facexlib; print('imports ok')"

# Smoke test (bundled samples) - official README quick path
python inference_gfpgan.py -i inputs/whole_imgs -o results -v 1.3 -s 2

# Your folder + V1.4 once the .pth is present
python inference_gfpgan.py -i inputs/my_faces -o results -v 1.4 -s 2

When it works, new files show up under results/ (full frames and cropped faces, depending on flags). Handy switches from the script help: -s scale (default 2), -only_center_face, -aligned for pre-aligned crops, -bg_upsampler realesrgan if you installed realesrgan.

Ever notice how the first clean restore of a ruined passport scan feels ridiculous next to the six dependency errors that came before it?

Common install errors and fixes

Stuff that shows up in real GitHub threads – not hypothetical lint.

1. ModuleNotFoundError: No module named 'torchvision.transforms.functional_tensor'
   Newer torchvision dropped that private module; basicsr/facexlib still import it (see TencentARC/GFPGAN issues such as #506 and related threads). Pin an older torchvision that still ships the module, or redirect the import to torchvision.transforms.functional in the offending basicsr file. Classic trigger: upgrade the torch stack weeks after a working install.
2. RuntimeError: Couldn't install gfpgan / basicsr metadata or wheel build errors
   Often missing Git, flaky network mid-clone, or Python 3.11+. Install Git, stay on 3.10, and install basicsr / facexlib before gfpgan.
3. Download “succeeds” but load dies
   HTML 404 saved as .pth. Re-fetch from official Releases and check size (~hundreds of MB; V1.4 commonly ~349 MB on mirrors).
4. CUDA not available / quiet CPU fallback
   python -c "import torch; print(torch.cuda.is_available())". False means a CPU wheel or driver mismatch – reinstall torch from the CUDA index. GFPGAN itself is fine.
5. Imports break after mixing pip and system site-packages
   Stay inside the conda/venv. which python and pip -V must agree.

Upgrade and uninstall

Code froze in practice after v1.3.8 (16 Sep 2022 notes include removing codeformer). “Upgrade” usually means new weights or a saner dependency pin – not a monthly app bump.

# Refresh source tree
cd GFPGAN
git fetch --tags
git checkout v1.3.8
pip install -r requirements.txt --upgrade
python setup.py develop

# Swap weights: new .pth into experiments/pretrained_models, pass -v

Uninstall / cleanup:

conda deactivate
conda env remove -n gfpgan
# or: pip uninstall gfpgan basicsr facexlib realesrgan -y
rm -rf /path/to/GFPGAN

Delete downloaded .pth files if you need the disk; nothing regenerates them until you wget again.

Next stop if you need full-frame polish: Real-ESRGAN on the background after the face pass. Different fidelity tradeoffs than CodeFormer-style restorers – same “fix the face, then the rest” order of operations.

FAQ

Is GFPGAN v1.3.8 free for commercial use?

Yes – Apache License Version 2.0 on the official repo. Read LICENSE in your clone before you ship anything.

Should I pick V1.3 or V1.4 weights after install?

Download both. Run the same five ugly scans through each and keep the folder you prefer. Generative priors can still drift identity if you restore twice or shove -s hard – keep the untouched original. Restoration isn’t lossless archaeology.

Why does identity sometimes slip even when the face looks sharper? That’s the open tradeoff of leaning on a GAN prior instead of a purely reconstructive filter – sharper doesn’t always mean “same person, pixel-faithful.”

Can I skip the GPU entirely?

Yes. Clean install doesn’t need custom CUDA extensions; a CPU torch wheel runs the script. Speed drops hard with -s 2 plus a Real-ESRGAN background pass. Weekend of family photos: fine. Bulk archive: borrow a CUDA box or the machine you already train on. “Optional GPU” in the README is honest – optional, not free.

Clone the repo, pin Python 3.10, drop V1.4 into experiments/pretrained_models, smoke-test on inputs/whole_imgs before you touch the real album.