GFPGAN Not Working? Fixes for the 9 Most Common Errors

Most GFPGAN failures are not subtle. They are a handful of dependency and environment problems that hit almost everyone, produce the same stack traces, and have known fixes. This guide covers the ones that actually stop people, with the reason each happens — because knowing why an error appears is what stops you hitting the next one.

Work through them in order. The first two account for the large majority of “GFPGAN not working” reports.

1. ImportError: cannot import name ‘rgb_to_grayscale’

This is the single most common GFPGAN error, and the one that catches people following an older tutorial.

ImportError: cannot import name 'rgb_to_grayscale' from
'torchvision.transforms.functional_tensor'

Why it happens. GFPGAN depends on basicsr, and basicsr imports from torchvision.transforms.functional_tensor. That module was deprecated and then removed in torchvision 0.17. If you install GFPGAN today with a current PyTorch stack, basicsr breaks on import — nothing to do with your photos, your GPU, or your model weights.

Fix A — patch the import (fastest). Find the offending file:

python -c "import basicsr, os; print(os.path.dirname(basicsr.__file__))"

Open basicsr/data/degradations.py and change line 8 from:

from torchvision.transforms.functional_tensor import rgb_to_grayscale

to:

from torchvision.transforms.functional import rgb_to_grayscale

The function still exists — it simply moved. One line, and the import resolves.

Fix B — pin torchvision below 0.17. If you would rather not edit an installed package:

pip install "torchvision<0.17"

This drags a matching older torch with it, so only do it in a dedicated virtual environment.

Fix C — install a maintained fork. Several community forks of basicsr ship the patch already. This is the cleanest option if you are building something you intend to maintain.

2. ModuleNotFoundError: No module named ‘basicsr’

ModuleNotFoundError: No module named 'basicsr'

Why it happens. Usually one of three things: you ran python inference_gfpgan.py without installing requirements; you installed into a different Python than the one you are running; or the basicsr build failed silently during pip install and you scrolled past the error.

Check which Python you are actually using:

which python      # macOS / Linux
where python      # Windows
python -m pip list | grep -i basicsr

If pip list does not show it, install with the same interpreter — python -m pip install ... rather than a bare pip, which may point elsewhere:

python -m pip install basicsr facexlib realesrgan
python -m pip install -r requirements.txt
python setup.py develop

If the build genuinely fails, read the first error in the output, not the last. basicsr compiles extensions and needs build tools present — on Windows that means the Visual Studio C++ build tools.

3. NumPy 2.x breaks the whole stack

A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x

Why it happens. NumPy 2.0 changed the C ABI. Packages compiled against NumPy 1.x — which includes much of this ecosystem — fail until they are rebuilt.

Fix. Pin NumPy in your environment:

python -m pip install "numpy<2"

This one is worth doing pre-emptively when you create the environment, because it manifests as several unrelated-looking errors deep inside other libraries.

4. “Unable to load face restoration model” in Automatic1111

You enable GFPGAN in the WebUI’s Extras tab, and the console prints a load failure or the checkbox does nothing.

Why it happens. Almost always a missing or partially downloaded weight file. The WebUI downloads GFPGANv1.4.pth on first use, and an interrupted download leaves a truncated file that fails silently on load.

Fix.

Look in stable-diffusion-webui/models/GFPGAN/.
Check the size of GFPGANv1.4.pth. A complete file is a few hundred megabytes. If it is a few kilobytes, the download failed.
Delete the truncated file and let the WebUI re-download it, or download it manually from the releases page of the official repository and drop it in that folder.
Restart the WebUI completely — a reload of the browser tab is not enough.

GFPGAN also needs its detection and parsing models (detection_Resnet50_Final.pth and parsing_parsenet.pth), which land in models/ or gfpgan/weights/. The same truncation problem applies to those, and a missing detection model produces a confusing “no face detected” result rather than an obvious download error.

Our Automatic1111 and ComfyUI setup guide covers the correct paths for each front-end in more detail.

5. CUDA out of memory

torch.cuda.OutOfMemoryError: CUDA out of memory.

Why it happens. GFPGAN’s own footprint is modest, but the upscaler it hands off to is not. If you run with -s 4 and a large input, or you have Stable Diffusion resident in VRAM at the same time, you run out.

Fixes, in order of what to try first:

Lower the upscale factor: -s 2 instead of -s 4.
Downscale the input before restoring. GFPGAN aligns and crops faces to a fixed size internally, so a 6000-pixel-wide scan gains you nothing on the face itself.
Add --bg_upsampler none to skip Real-ESRGAN on the background, which is usually what actually exhausts the memory.
Close other GPU consumers, including a running WebUI.
Fall back to CPU with --device cpu. Much slower, but it completes.

6. No faces detected in an image that clearly has a face

GFPGAN only restores regions its detector identifies as faces. If detection fails, you get your input back essentially unchanged.

Common causes:

The face is too small in the frame. The detector needs a reasonable pixel area — crop closer and retry.
Extreme angle or heavy occlusion. Strong profiles and half-covered faces frequently fail.
The detection model did not download. See error 4 above.
The image is severely degraded. There is a floor below which no detector fires.

If you need the whole image upscaled regardless of face detection, that is Real-ESRGAN’s job, not GFPGAN’s — they solve different problems.

7. The restored face looks like a different person

Not a crash, but the most common quality complaint, and worth understanding.

GFPGAN reconstructs detail using a generative prior — a model of what human faces look like in general. When the input carries very little identity signal, the prior contributes proportionally more, and the output drifts toward a plausible face rather than your face. This is inherent to the approach, not a bug.

What helps:

Start from the best source you have. Re-scan the original print rather than restoring a photo of a screen.
Do not restore an already-restored image. Repeated passes compound the drift badly.
Try CodeFormer with a high fidelity weight for comparison — it exposes a fidelity/quality dial that GFPGAN does not. Our CodeFormer vs GFPGAN comparison covers when each wins.

8. Downloads fail or hang on first run

GFPGAN fetches weights at runtime, and in restricted networks that fetch fails.

Fix. Download the files manually and place them where the code expects them — typically gfpgan/weights/ for the detection and parsing models, and experiments/pretrained_models/ for the main checkpoint. The traceback names the exact path it tried; use that path rather than guessing.

Behind a proxy, set HTTP_PROXY and HTTPS_PROXY before running, or download on another machine and copy the files across.

9. It runs, but takes minutes per image

You are almost certainly on CPU without realising it. Verify:

import torch
print(torch.cuda.is_available())

If that prints False on a machine with an NVIDIA GPU, you installed a CPU-only build of PyTorch. Reinstall from the correct index URL for your CUDA version, following the selector on the official PyTorch site rather than a copied command from a tutorial — the right command depends on your driver.

A clean environment beats debugging

If several of these are hitting at once, do not fix them one at a time. Start over with an isolated environment and pin the pieces that break:

python -m venv gfpgan-env
source gfpgan-env/bin/activate     # Windows: gfpgan-env\Scripts\activate
python -m pip install "numpy<2"
python -m pip install torch torchvision --index-url <correct URL for your CUDA>
python -m pip install basicsr facexlib realesrgan
# then apply the functional_tensor patch from error 1

Full step-by-step setup, including the Windows specifics, is in our GFPGAN installation guide.

Frequently Asked Questions

Why does GFPGAN break after a fresh install when it worked last year?

Because the ecosystem moved and GFPGAN’s pinned dependencies did not. The torchvision.transforms.functional_tensor removal in torchvision 0.17 and the NumPy 2.0 ABI change both landed after GFPGAN’s last significant release, so a clean install today pulls versions the code was never tested against.

Do I need a GPU to run GFPGAN?

No. It runs on CPU with --device cpu, and for a handful of photos that is perfectly workable — expect tens of seconds to a couple of minutes per image rather than under a second. A GPU only becomes necessary for batch work.

Is there a way to avoid the dependency problems entirely?

Yes — run it hosted. The Replicate endpoint and the official Hugging Face Space both execute the real model with no local environment at all. The trade-off is that your image is uploaded to their servers, so use photos you are comfortable sending.

Which GFPGAN version should I use?

v1.4 is the usual default and what most integrations ship with. v1.3 is worth trying if v1.4 produces over-smoothed skin on your particular source photos. Both are on the official repository.