GFPGAN has had no release since 2022, and three different version numbers describe the same project

The last commit is dated 2024-07-26 and the newest release tag is from 2022

Two dates define the state of this repository. The last push is 2024-07-26, which is more than two years before the current date. The release tags are older still: v1.3.8 and v1.3.7 are both dated 2022-09-16, minutes apart, and v1.3.4 is dated 2022-07-13. The repository is not archived, so nothing has been declared finished, but no commit and no tagged release have landed in a long time. So what a reader cannot get from the project is a statement that it works with a current PyTorch, a current CUDA, or a current NumPy, because nobody has verified it and nobody has said it broke. The consequence is that the dependency list in this article describes an upper bound on what was known to work when it was written, not a supported combination, and the compatibility work moves to whoever installs it.

The package version, the model version, and the release tag are three different numbers

GFPGAN is versioned three ways at once, and they do not line up. The package line runs through v1.3.8. The model versions are separate, and the inference script exposes them through a version flag whose documented options are `1 | 1.2 | 1.3` with a default of 1.3. The Updates section then announces a V1.4 model that produces slightly more detail and better identity retention than V1.3, and links its weights. Both the v1.3 and the v1.4 weight files are downloaded from the same v1.3.0 release, which is where the confusion starts: the release tag a file lives under and the version a flag expects are unrelated. So what the script cannot do, as documented, is select v1.4, and a user who downloads the newer weights has no documented route to them. The help text also stops mid-entry at `-suffix` with no description, so the last option is undocumented as well.

The default background upsampler is a separate package that the same page asks you to install

The documented inference command touches two packages beyond GFPGAN itself. The background upsampler option defaults to `realesrgan`, and the tile size option defaults to 400, with 0 meaning no tiling during testing. So a plain face restoration run still pulls in Real-ESRGAN for the non-face regions unless you change that default, and the installation section confirms this is a separate requirement rather than a bundled one, with a comment explaining that if you want to enhance the background regions you also need to install the realesrgan package. What the help output cannot tell you is what happens when the default is left alone and the package is missing. There is no error message documented, no fallback named, and no note that the flag is safe to override. The consequence is that a first run on a fresh environment can fail for a component the reader was not told was on the critical path.

requirements.txt pins a nightly TensorBoard and nothing else exactly

The dependency list is short, and only two entries carry a floor: `basicsr>=1.4.2` and `facexlib>=0.2.5`, plus `torch>=1.7`. Everything else is a bare name, including `tb-nightly`, which is a nightly build of TensorBoard rather than a numbered release, along with torchvision, lmdb, numpy, opencv-python, pyyaml, scipy, tqdm, and yapf. So what a fresh install cannot give you is a reproducible environment, because the nightly package resolves to whatever build is current on the day you install, and the two libraries with real constraints still float upward within their major versions. The consequence is that a fresh clone in a year will assemble a TensorBoard nobody tested against this code, and if an install breaks, the file gives you no way to tell whether the cause is a nightly build or a library that moved.

basicsr and facexlib are installed twice and the version floors arrive last

The installation block is one script, and the ordering inside it matters more than it looks:

# Install basicsr - https://github.com/xinntao/BasicSR
# We use BasicSR for both training and inference
pip install basicsr

# Install facexlib - https://github.com/xinntao/facexlib
# We use face detection and face restoration helper in the facexlib package
pip install facexlib

pip install -r requirements.txt
python setup.py develop

# If you want to enhance the background (non-face) regions with Real-ESRGAN,
# you also need to install the realesrgan package
pip install realesrgan

Only the third line group, `pip install -r requirements.txt`, brings in the version floors `basicsr>=1.4.2` and `facexlib>=0.2.5`. The two explicit installs before it are redundant, since each one installs whatever is current and pip then reconciles them against the floors. So a reader following the script literally installs two libraries twice, while anyone who skips straight to the requirements file reaches the same end state with less work. The last line, `python setup.py develop`, is a setuptools command that modern setuptools has deprecated.

setup.py reads its version out of git, and falls back to unknown without a checkout

The packaging script is worth reading because it explains what a built artifact contains. It writes a generated version file at `gfpgan/version.py` by combining three inputs: the contents of the `VERSION` file at the repository root, the current time, and a short git hash. That hash comes from shelling out to `git rev-parse HEAD` in a deliberately minimal environment that keeps only a few variables and forces the language settings to C, and it is truncated to seven characters. If the `.git` directory is absent, the function returns the string `unknown` instead. So what a distribution built outside a git checkout cannot provide is a meaningful commit reference, and the version tuple is assembled by splitting the VERSION string on dots and quoting anything that is not a digit. The consequence is that provenance in an installed package depends on where it was built from, which is a detail to check if you are auditing a wheel rather than a local install.

The hosted demos run from a Cog container, not from the README install steps

The repository root carries `cog.yaml` and `cog_predict.py` alongside `assets/`, and the online demos are hosted on Replicate and on a Hugging Face Space built with Gradio, with two Colab notebooks also linked, one for GFPGAN and one for the original paper model. Cog is the container definition used for those hosted endpoints, so the environment that actually serves the demo is described in that file rather than in the installation section. So what the README cannot tell you is how the hosted version resolves its dependencies, because the pip steps shown are aimed at a local install. The consequence is that reproducing a hosted demo's exact behaviour means reading the Cog configuration, and the two Colab links being split into a current model and a paper model is a reminder that the original weights need the separate installation path in PaperModel.md.

Editorial conclusion

GFPGAN suits a researcher reproducing the published method, or an application that needs a face restoration step and can supply its own environment and pin its dependencies itself. It does not suit a team expecting upstream fixes against a current PyTorch, since the last commit is dated 2024-07-26 and the newest tag predates that by two years, nor one expecting a documented option to select the v1.4 weights. Before building on it, read the LICENSE file rather than the repository license field, pin the nightly TensorBoard to a known version, and confirm which model version the inference script will actually accept.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes