QWE AI Academy Here’s an uncomfortable truth every CodeFormer tutorial dances around: the tool hasn’t had a real version bump in almost four years. The only tagged release is v0.1.0 from August 10, 2022. New weight files (colorization, inpainting, stage2) got dropped into that same release bucket through mid-2023 without a version change. And yet it’s still one of the best free AI photo enhancers you can self-host – if you can get past the install.
This guide is for that install. I’ll skip the marketing about codebook priors and get straight to the two things that will actually break your deployment: the basicsr namespace collision that hits half of fresh clones, and the silent CPU fallback that turns your 3090 into a paperweight.
Why deploy CodeFormer locally (and when not to)
CodeFormer restores faces in blurry, old, or AI-generated images. The NeurIPS 2022 paper by Shangchen Zhou et al. from S-Lab, NTU frames restoration as a code-prediction task over a learned discrete codebook – that’s why it holds up on severely degraded inputs where GFPGAN starts hallucinating.
Deploy locally if you need batch processing, video frames, or predictable latency. Skip the local install and use the Hugging Face Space or Replicate if you have fewer than a few dozen images – the official demos are maintained by the authors themselves. Quick stop before you go further: the license is CC BY-NC-SA 4.0. No commercial use without written authorization. If you’re building a paid product on top of this, stop here.
System requirements
The repo doesn’t publish hard specs. The figures below come from community reports and the Dockerfile that’s been circulating since 2023 – treat them as field estimates, not official minimums.
| Component | Minimum | Recommended |
|---|---|---|
| OS | Ubuntu 20.04 / Windows 10 | Ubuntu 22.04 |
| Python | 3.8 | 3.8 (don’t go higher without pain) |
| PyTorch | 1.7.1 | 1.13.1 or 2.1.0 + matching CUDA |
| GPU | None (CPU works, slowly) | NVIDIA with 6 GB+ VRAM, CUDA 11.7 or 11.8 |
| RAM | 8 GB (community-reported) | 16 GB |
| Disk | ~2 GB for weights + repo | 5 GB (leave room for outputs) |
Python 3.8 is the version the official README pins, and I’d stick to it. There are reports of 3.10 and 3.11 users hitting import errors that never appear on 3.8.
Install the AI photo enhancer step by step
Two paths: bare-metal conda (what the README shows) or Docker (what I’d actually recommend). Conda first, because it’s what breaks most often and you’ll want the fix notes nearby.
Option A: conda (bare metal)
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
# optional: only if you want dlib face detection
# conda install -c conda-forge dlib
python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py CodeFormerThe python basicsr/setup.py develop line is the one people miss or run from the wrong directory. It has to run from the repo root, and it installs the local basicsr/ as an editable package. Skip it and nothing works.
Option B: Docker (recommended)
The community Dockerfile from Lindevs uses nvidia/cuda:12.0.0-runtime-ubuntu22.04 as base (as of 2023 – verify the tag is still current before building) and bakes the weight downloads into the build. Requires an NVIDIA GPU on the host and nvidia-container-toolkit installed.
docker build -t codeformer .
docker run -it --rm --gpus all
-v ~/inputs:/codeformer/inputs
-v ~/results:/codeformer/results
codeformer -w 0.5 --input_path inputs/test.jpgWhy Docker wins here: it sidesteps the basicsr namespace bug entirely. The build environment is clean and isolated from whatever you have on your host Python.
First run and verification
Grab a test image, then run:
# cropped 512x512 face
python inference_codeformer.py -w 0.5 --has_aligned --input_path inputs/cropped_faces
# whole image with background upscaling
python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --face_upsample --input_path inputs/whole_imgsThe w flag lives in [0, 1]. Per the official README, smaller w yields higher visual quality; larger w stays closer to the original degraded face. 0.5 is the balanced default for restoration, 0.7-1.0 when identity fidelity matters more than looking sharp.
Output lands in results/. If you see restored faces there and the terminal didn’t print the CPU warning, you’re done. If it did print the CPU warning – see the next section.
Pro tip: Always confirm the GPU is actually being used before running a batch:
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')". CodeFormer will silently fall back to CPU without stopping the job, and processing times balloon by orders of magnitude – you won’t notice until the batch is halfway done.
The two errors that will actually happen to you
Not “common” errors. The specific two that hit almost every fresh install.
1. basicsr import collision
You’ll see one of these:
ModuleNotFoundError: No module named 'basicsr'
# or
ImportError: cannot import name 'gpu_is_available' from 'basicsr.utils.misc'
# or
ModuleNotFoundError: No module named 'basicsr.version'What’s happening: pip installs the PyPI basicsr package, but this repo ships its OWN basicsr/ directory with modified code. Python’s import resolver picks the wrong one. Issue #193 has the community-verified fix: rename the local folder.
mv basicsr cfbasicsr
# then update imports OR just re-run setup:
python cfbasicsr/setup.py developAlternative fix: uninstall the PyPI package (pip uninstall basicsr) and rely only on the local one via setup.py develop. This is cleaner if you’re not running any other project that needs BasicSR.
2. Silent CPU fallback despite a working GPU
Warning shows up: “Running on CPU now! Make sure your PyTorch version matches your CUDA.” But torch.cuda.is_available() returns True. What?
Per community discussion on GitHub issue #315, this happens when your PyTorch was installed with a CUDA build that doesn’t match the CUDA toolkit on your system, or when face_restoration_helper.py receives a device=None argument that doesn’t get properly resolved. The dirty fix from discussion #7817: edit face_restoration_helper.py and hardcode the device line to self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu').
The cleaner fix: match your torch install to your CUDA version exactly. If you have CUDA 11.8, install torch==2.1.0+cu118 from the PyTorch wheel index (as of this writing – check the PyTorch install page for the current recommended version). Don’t just pip install torch.
A brief digression on why this project feels frozen in amber
CodeFormer works. It works well. But the release cadence – one tag in Aug 2022, silent asset updates until mid-2023, then radio silence – makes me wonder if the S-Lab team moved on to other research and left this to the community. That’s not a criticism. Academic code gets published, gets its citations, and gets left alone. The install friction you’re fighting is basically the sedimentary layer of four years of PyTorch and Python moving on while this repo stayed put.
Which raises a question I don’t have a clean answer to: at what point does a beloved research repo become tech debt for its users? I’ll leave that one open.
Upgrade and uninstall
There’s no upgrade path because there’s nothing to upgrade to – v0.1.0 is still the only release as of this writing (verify at the releases page before you assume). Pulling the latest master with git pull gets you any doc fixes but no new model.
Uninstall is boring:
conda deactivate
conda env remove -n codeformer
rm -rf ~/CodeFormer # or wherever you cloned itFor Docker: docker rmi codeformer and delete the input/output volumes if you mounted them somewhere permanent.
FAQ
Can I run CodeFormer without a GPU?
Yes. Cropped-face mode on CPU is tolerable for one-off images. Whole-image mode with Real-ESRGAN background upscaling is a different story – processing times stretch by orders of magnitude, so set your expectations before kicking off a batch overnight.
Does CodeFormer work on bodies, hands, or full scenes?
No. It’s a face-only model. The pipeline detects faces, restores them, then pastes them back – the rest of the pixels are handled by Real-ESRGAN if you pass --bg_upsampler realesrgan. For hands, you’re in different-toolchain territory (ControlNet hand-fixing in ComfyUI is where most people end up). Whether CodeFormer is the right face restoration tool versus other options really depends on your input material – benchmark a few on your own photos before committing to one.
Which weight file goes where?
Run download_pretrained_models.py and it handles placement automatically. Manual download from the v0.1.0 release page: codeformer.pth (359 MB) → weights/CodeFormer/, face detection models (detection_Resnet50_Final.pth at 104 MB, parsing_parsenet.pth) → weights/facelib/, RealESRGAN weights → weights/realesrgan/.
Next step: clone the repo, run through Option B (Docker) with the Lindevs Dockerfile, and drop your first test image into ~/inputs. If Docker’s not available, do Option A but keep the mv basicsr cfbasicsr command ready – you’ll probably need it within the first ten minutes.