GFPGAN vs CodeFormer Face Restoration: Settings and APIs

A face-restoration model can make a damaged portrait look sharper while quietly changing the person. As a practical starting point, GFPGAN favors simple natural cleanup, while CodeFormer exposes more control when identity matters. New 2026 papers point toward reference-guided, diffusion-based, and edge-friendly restorers, but they are not yet drop-in replacements for either established implementation.

Start with the damage pattern, not the model name

Face restoration is not ordinary upscaling. A super-resolution model enlarges the image and estimates missing texture across the frame; a blind face-restoration model also uses a learned facial prior to reconstruct eyes, skin, hair, and other features that may no longer be present. That makes the output more convincing, and makes identity drift possible.

A cautious workflow keeps the untouched original, restores a copy, and compares the face at 100% before judging the enlarged result.

Where the simple table breaks

For mild blur or an AI-generated face with small defects, try GFPGAN first when you want cleanup without a large reconstruction. For a warped, tiny, or heavily degraded face, CodeFormer is the more useful first experiment because its fidelity setting makes the trade-off visible.

Scratches and fading across the whole scan are a separate problem. GFPGAN and CodeFormer focus on faces; process the face and background as separate concerns, then inspect the hairline, glasses, and composite grain. For multiple faces or unusual accessories, use an aligned-face or center-face option when the wrapper exposes one.

Do not call a sharper result “recovered evidence.” When the source has lost the pixels, the restorer is estimating a plausible face. That distinction matters for family archives and especially for legal, journalistic, or identification-related work.

GFPGAN, CodeFormer, and 2026 research are different maturity levels

GFPGAN and CodeFormer are formally released open-source research implementations. The official GFPGAN repository documents Python 3.7+, PyTorch 1.7+, pretrained weights, and command-line inference. The CodeFormer repository documents local inference, whole-image and video modes, and a fidelity weight from 0 to 1.

The 2026 projects below are research signals rather than equivalent hosted products. The linked paper records do not document the same combination of downloadable workflow, production API, license clarity, and predictable billing.

What GFPGAN does well—and where it changes faces

GFPGAN uses a pretrained generative facial prior, including a StyleGAN2-based prior in the published method, to restore degraded faces. Its official README says v1.3 produces more natural results and handles very low-quality inputs better, while warning that v1.3 is not always better than v1.2 and can slightly change identity. GFPGAN is released under the Apache License 2.0.

The official version comparison is qualitative, not a numeric benchmark. It describes v1.2 as sharper but occasionally unnatural, and v1.3 as more natural but not very sharp. GFPGAN is therefore a sensible first pass when the original face is broadly correct, but it does not expose CodeFormer’s explicit identity-versus-reconstruction dial.

What CodeFormer’s fidelity weight actually trades

CodeFormer uses a codebook lookup transformer for blind face restoration. Its central control is the fidelity weight w, whose documented range is [0, 1]. The authors state that smaller w generally produces a higher-quality-looking result, while larger w gives higher fidelity to the input identity and content.

w is a trade-off, not a quality slider: a low value can produce a cleaner face by inventing detail, while a high value can preserve the source more faithfully and leave blur, compression, or other damage visible. CodeFormer’s whole-image path also fuses the restored face back into the scene, and the README warns that this may damage hair texture at the face/background boundary.

CodeFormer uses the NTU S-Lab License 1.0. Read the license before redistribution or commercial integration rather than assuming that a hosted endpoint and the repository have identical terms.

The published benchmark boundary

There is useful published evidence, but not a universal 2026 head-to-head leaderboard for every model and damage type. The 2023 ICCV paper on iterative diffusion restoration evaluated GFPGAN and CodeFormer alongside other baselines on CelebA-HQ.

On one synthetic-degradation table, the paper reported the following figures:

These are protocol-specific figures, not a 2026 universal ranking. The same paper used its own datasets, degradation process, implementations, and evaluation method. They are useful context for why newer restorers focus on authenticity, but they do not predict the best result on a particular family photo.

Parameter tuning that avoids the plastic-face failure

The “plastic face” problem comes from treating restoration strength, identity fidelity, and compositing as one control. They are separate decisions.

A usable CodeFormer starting grid

Run the same input through three settings before changing the image or model:

The ranges reflect the documented trade-off, not a guarantee for every wrapper. The CodeFormer README uses w=0.5 for aligned face restoration, w=0.7 for whole-image enhancement, and w=1.0 in its example video command.

If the result looks like a wax mask, first compare a higher w, lower face visibility or blend if the host provides it, and a crop with more original context. Blending some original texture back can reduce the pasted-on look even when the restored crop is sharp.

What to inspect between passes

1. Identity: eye spacing, nose width, mouth shape, face outline, and distinctive marks.
2. Texture: pores, freckles, beard stubble, hair strands, and film grain.
3. Accessories: glasses, earrings, hats, and hair crossing the face.
4. Integration: lighting, color, grain, and the face/background edge.
5. Repeatability: whether a second pass changes the face again.

GFPGAN does not provide the same w dial. Use its model-version and visibility/blend controls conservatively. The official repository says v1.3 can be run twice, but repeated restoration should remain an experiment; if the second pass changes identity or texture, keep the first output.

Local deployment: useful control, dated dependencies

Local inference keeps the image on your machine, but moves Python, PyTorch, model weights, CUDA, detector packages, and file permissions onto you.

GFPGAN local path

The official repository documents a clean version that does not require custom CUDA extensions:

git clone https://github.com/TencentARC/GFPGAN.git
cd GFPGAN
pip install basicsr
pip install facexlib
pip install -r requirements.txt
python setup.py develop
wget https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth \
  -P experiments/pretrained_models
python inference_gfpgan.py -i inputs/whole_imgs -o results -v 1.3 -s 2

The README lists Python >=3.7 and PyTorch >=1.7; NVIDIA GPU and CUDA are optional paths in the documented setup. The command supports folders, final scale, background upsampling, center-face-only processing, aligned faces, and automatic extension handling.

CodeFormer local path

CodeFormer’s official environment is more involved:

git clone https://github.com/sczhou/CodeFormer
cd CodeFormer
conda create -n codeformer python=3.8 -y
conda activate codeformer
pip3 install -r requirements.txt
python basicsr/setup.py develop
python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py CodeFormer

The repository lists PyTorch >=1.7.1 and CUDA >=10.1. dlib is optional for its detector and face-cropping path; FFmpeg is needed for the documented Windows and Mac video workflow.

For a 512×512 aligned face, the official example is:

python inference_codeformer.py -w 0.5 --has_aligned \
  --input_path inputs/cropped_faces

For whole-image enhancement, the README uses -w 0.7 and optionally adds --bg_upsampler realesrgan and --face_upsample. The repository does not publish a dependable VRAM, throughput, or latency requirement, so test the exact environment instead of promising a hardware minimum.

API cost and integration choices

Hosted inference is easier to prototype, but price and license remain separate decisions.

Dated hosted cost table

The official GFPGAN Replicate page, CodeFormer Replicate page, and Real-ESRGAN Replicate page list approximate costs. Prices were checked September 1, 2026. The two face models state typical completion within 3 seconds on Nvidia L40S; estimates vary with inputs.

The CodeFormer Replicate page explicitly says its API version cannot be used commercially. That statement applies to that hosted deployment; verify the terms of another provider separately.

The fal CodeFormer API documentation labels its endpoint for commercial use and exposes fidelity with a default of 0.5, upscale_factor with a default of 2, optional face upscaling, alignment, center-face selection, and a seed. It does not publish a price, so do not infer fal’s cost from Replicate’s estimate.

Minimal hosted workflow

The fal documentation shows a JavaScript client workflow:

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/codeformer", {
  input: {
    image_url: "https://example.com/input.jpg",
    fidelity: 0.7,
    upscale_factor: 2,
    face_upscale: true
  },
  logs: true
});

console.log(result.data);

For longer jobs, the same documentation provides queue submission, status polling, result retrieval, and webhook callbacks. Keep FAL_KEY or an equivalent provider key on your server, not in browser or mobile code.

What real users still run into

Across the retrieved user threads, setup reports, and upscaling error reports, people describe a visually improved face that no longer looks like the same person and local integration errors. These are workflow reports, not controlled benchmarks.

“I find CodeFormer tends to 'invent' a face rather than fixing it.” — u/TheMemo, r/StableDiffusion

The operational lesson is simple: compare outputs on representative faces and pin the environment for a batch pipeline.

FAQ: GFPGAN and CodeFormer face restoration

Is GFPGAN or CodeFormer better for old photos?

As a rule of thumb, start with GFPGAN for a recognizable face and natural cleanup; use CodeFormer when severe degradation or likeness control matters more.

What CodeFormer fidelity value preserves identity?

Higher w values favor fidelity to the input, while lower values generally favor a cleaner but more invented result. Compare 0.5, 0.7, and 0.9, then keep the output that preserves distinctive features rather than the sharpest eyes.

Should I restore before upscaling?

As a practical workflow, start by restoring the face on a copy and upscale the finished image afterward. A combined workflow such as Real-ESRGAN with face enhancement is an exception, but it still needs an identity and face/background check.

Can these models recover details that are fully blurred away?

No model can reliably recover information that was never captured. GFPGAN and CodeFormer can generate plausible facial detail, so a sharper eye or mouth is not proof that the original detail was recovered.

Are the 2026 models ready to replace GFPGAN or CodeFormer?

The linked papers show important directions, including edge deployment, high-dimensional conditioning, and same-identity references, but not yet a broadly available replacement with the same local and hosted workflow documentation.

Can I use CodeFormer’s Replicate API commercially?

The CodeFormer Replicate page says its API version cannot be used commercially. The underlying repository has its own NTU S-Lab License 1.0, and other providers may publish different terms.

The practical choice is a trade-off between invention and control

Select three representative crops: mild blur, heavy blur, and a scratched low-resolution portrait. Run GFPGAN plus CodeFormer at w=0.5, 0.7, and 0.9, keep the original beside every output, and reject any result that changes identity-critical features. Send whole-image enlargement to a separate upscaler when the background needs repair.

For the next stage, see the Real-ESRGAN download and GUI guide and the free AI video upscalers guide.