CodeFormer

CodeFormer v0.1.0 models

PyTorch previous versions

Overview

CodeFormer is a blind face-restoration model published with the NeurIPS 2022 paper Towards Robust Blind Face Restoration with Codebook Lookup Transformer. It can restore faces in cropped images, complete photos, and videos.

This guide installs the command-line version on 64-bit Windows 10 or Windows 11. An NVIDIA GPU is recommended, although CodeFormer can run on a CPU much more slowly.

The upstream installation instructions still specify Python 3.8 and do not provide a fully pinned dependency file. The environment below therefore uses Python 3.8 with PyTorch 1.12.0 and torchvision 0.13.0, a matching pair published in PyTorch’s official previous-version archive. This older environment is intentional and avoids compatibility errors caused by installing current packages into an older project.

Install the Prerequisites

Install the following applications:

• Git for Windows
• Miniconda for Windows
• The current NVIDIA driver when using a supported NVIDIA GPU

Open Anaconda Prompt after installation and verify Git and Conda:

git --version
conda --version

There is no need to add Conda directories to the system PATH manually when commands are run from Anaconda Prompt.

For an NVIDIA GPU, confirm that Windows can see the driver and graphics card:

nvidia-smi

The CUDA version displayed by nvidia-smi is the newest CUDA runtime supported by the installed driver. It does not mean that the same standalone CUDA Toolkit is installed. Normal CodeFormer inference uses the CUDA runtime supplied with PyTorch, so a separate Toolkit and the nvcc command are not required.

Download CodeFormer

Choose a working directory, then clone the official repository:

git clone https://github.com/sczhou/CodeFormer.git
cd CodeFormer

Run all remaining commands from the repository root, where inference_codeformer.py and the basicsr directory are visible.

Create the Conda Environment

Create and activate a dedicated Python 3.8 environment:

conda create -n codeformer python=3.8 -y
conda activate codeformer
python -m pip install --upgrade "pip<25"

The pip limit retains Python 3.8 support.

NVIDIA GPU

Install the matching CUDA 11.3 build of PyTorch 1.12.0:

conda install -y pytorch==1.12.0 torchvision==0.13.0 torchaudio==0.12.0 cudatoolkit=11.3 -c pytorch

This package installs the required CUDA runtime inside the Conda environment. It does not replace the Windows display driver.

CPU Only

Use this command instead when the computer does not have a compatible NVIDIA GPU:

conda install -y pytorch==1.12.0 torchvision==0.13.0 torchaudio==0.12.0 cpuonly -c pytorch

Do not install both variants in the same environment.

Install CodeFormer

Install the remaining dependencies and register the bundled BasicSR package:

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

The separate gradio package from the original notes is not required for command-line inference.

Verify the installed versions and the selected compute device:

python -c "import torch, torchvision; print('torch:', torch.__version__); print('torchvision:', torchvision.__version__); print('CUDA available:', torch.cuda.is_available()); print('device:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')"

For the GPU installation, CUDA available should be True. A CPU-only installation should report False and CPU.

Download the Pretrained Models

Download the face detection, face parsing, and CodeFormer model files with the repository scripts:

python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py CodeFormer

The files are stored under weights/facelib and weights/CodeFormer. If an automatic download fails, download the files from the official v0.1.0 release and place them in the corresponding directories.

Restore a Cropped Face

Cropped and aligned inputs are resized to 512 × 512 by the inference script. Run:

python inference_codeformer.py -w 0.5 --has_aligned --input_path "C:/Photos/aligned-face.png" --output_path "C:/Photos/CodeFormer-output"

To create aligned faces from a folder of source images, install the optional dlib detector and its model first:

conda install -y -c conda-forge dlib
python scripts/download_pretrained_models.py dlib
python scripts/crop_align_face.py -i "C:/Photos/source" -o "C:/Photos/aligned"

Then process the complete folder:

python inference_codeformer.py -w 0.5 --has_aligned --input_path "C:/Photos/aligned" --output_path "C:/Photos/CodeFormer-output"

Restore Faces in a Complete Photo

CodeFormer can detect and restore faces without preparing them first:

python inference_codeformer.py -w 0.7 --input_path "C:/Photos/input.jpg" --output_path "C:/Photos/CodeFormer-output"

Add Real-ESRGAN when the background and restored faces should also be upscaled:

python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --face_upsample --input_path "C:/Photos/input.jpg" --output_path "C:/Photos/CodeFormer-output"

Real-ESRGAN uses more memory and is particularly slow on a CPU. Omit --bg_upsampler realesrgan and --face_upsample when only face restoration is needed.

Restore Faces in a Video

Install FFmpeg from Conda and verify that the environment uses it:

conda install -y -c conda-forge ffmpeg
ffmpeg -version

Process an MP4, MOV, or AVI file:

python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --face_upsample --input_path "C:/Videos/input.mp4" --output_path "C:/Videos/CodeFormer-output"

CodeFormer does not require the Python packages named ffmpeg or ffmpeg-python for this command. Installing FFmpeg through Conda avoids conflicts with unrelated packages that use those names.

Choose the Fidelity Weight

The -w value accepts a number from 0 to 1:

Start with 0.5 for an aligned face or 0.7 for a complete photo, then compare several values. Face restoration can generate details that were not present in the source, so do not treat the result as historical or forensic evidence.

Without --output_path, results are written below the repository’s results directory. With --output_path, they are written to the selected folder.

Optional Colorization and Inpainting

Colorize a cropped and aligned grayscale face:

python inference_colorization.py --input_path "C:/Photos/aligned-face.png"

Run face inpainting on a cropped and aligned image whose damaged area has been painted white:

python inference_inpainting.py --input_path "C:/Photos/masked-face.png"

The repository includes examples in inputs/masked_faces.

Troubleshooting

CUDA Is Not Available

Check the driver and the PyTorch build from the activated codeformer environment:

nvidia-smi
conda activate codeformer
python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

If the installed PyTorch version contains cpu or CUDA remains unavailable, create a clean environment and install the GPU command from this guide again. Installing a standalone CUDA Toolkit does not convert a CPU-only PyTorch package into a CUDA-enabled package.

BasicSR Cannot Be Imported

Confirm that the prompt is in the cloned repository and rerun the development installation:

cd CodeFormer
python basicsr/setup.py develop
python -c "import basicsr; print(basicsr.__file__)"

torchvision Import Errors

Errors involving removed torchvision modules usually indicate an incompatible torch and torchvision combination. Use the paired versions in this guide and avoid upgrading either package independently.

No Input File Is Found

The current inference script scans image files ending in JPG, JPEG, or PNG and video files ending in MP4, MOV, or AVI. Quote paths that contain spaces and use an explicit filename or a directory containing supported images.

GPU Memory Is Exhausted

First remove background and face upsampling. If Real-ESRGAN is required, reduce its tile size:

python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --face_upsample --bg_tile 200 --input_path "C:/Photos/input.jpg" --output_path "C:/Photos/CodeFormer-output"

Process smaller images or individual files if memory errors continue.

A Model Download Is Corrupted

Close the process, remove the incomplete model file from weights/CodeFormer or weights/facelib, and run the corresponding download command again. Avoid loading model files from untrusted mirrors.

Maintenance and License

Activate the environment whenever CodeFormer is used:

conda activate codeformer
cd CodeFormer

Record a working environment before changing dependencies:

conda env export --from-history > environment-history.yml
python -m pip freeze > requirements-lock.txt

The upstream requirements.txt does not pin most packages, so a future reinstall may resolve different versions. Keep the exported files with your local setup notes.

CodeFormer is distributed under the NTU S-Lab License 1.0. The license permits redistribution and use for non-commercial purposes under its conditions; commercial redistribution or use requires contacting the contributors. Review the license before publishing or using the software in a commercial service.

The project authors identify only their Hugging Face, Replicate, and OpenXLab deployments as official hosted demos. Use the local repository or links published in the official README when handling private photos.