Conda 环境安装：PyTorch + CUDA + BasicSR 一步步搭

前置准备

1. 安装 Anaconda 或 Miniconda（推荐 Miniconda，更轻量）
2. 确认 NVIDIA 驱动正常：nvidia-smi 能输出显卡信息
3. 可选：安装 git（Windows 用户装 Git for Windows）

全平台安装流程

第一步：Clone 代码

git clone <仓库地址>
cd CodeFormer

第二步：创建 Conda 环境

conda create -n codeformer python=3.8 -y
conda activate codeformer

为什么是 Python 3.8？ CodeFormer 的依赖（dlib、旧版 PyTorch）在 Python 3.8 上兼容性最好。Python 3.10 也能跑，但可能遇到 dlib 编译问题。

第三步：安装 PyTorch

按你的 CUDA 版本选一条（在 codeformer 环境里执行）：

# CUDA 11.7（最常用，兼容性好）
pip install torch==1.12.1+cu117 torchvision==0.13.1+cu117

# CUDA 11.8
pip install torch==1.13.1+cu118 torchvision==0.14.1+cu118

# CUDA 12.1（新卡推荐）
pip install torch==2.1.0+cu121 torchvision==0.16.0+cu121

# 纯 CPU（不推荐）
pip install torch torchvision

安装完验证：

python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
# 应输出 True 和你的显卡名

第四步：安装 CodeFormer 依赖

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

basicsr/setup.py develop 会把 BasicSR（CodeFormer 基于的训练框架）以开发模式装入环境，让 CodeFormer 的子模块能正确 import。

第五步：安装 dlib（人脸检测用）

conda install -c conda-forge dlib

Windows 用户注意：dlib 在 Windows 上安装很容易出错（需要 CMake + C++ Build Tools）。如果 conda 安装失败，参考 dlib 安装失败排查 页。

如果不想装 dlib，CodeFormer 还支持 YOLOv5-face 做人脸检测——dlib 是可选的。

第六步：安装 ffmpeg（视频处理用）

# Conda 方式
conda install -c conda-forge ffmpeg

# Ubuntu apt 方式
sudo apt-get install ffmpeg

# Windows：装完 ffmpeg 后确保 ffmpeg.exe 在 PATH 里

验证：ffmpeg -version

第七步：下载预训练模型

详见 预训练模型下载 页。快速命令：

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

一键安装脚本（Linux）

如果你想自动化，可以写一个 shell 脚本：

#!/bin/bash
set -e

git clone <仓库地址>
cd CodeFormer

conda create -n codeformer python=3.8 -y
source activate codeformer

# PyTorch CUDA 11.7
pip install torch==1.12.1+cu117 torchvision==0.13.1+cu117

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

conda install -c conda-forge dlib -y
conda install -c conda-forge ffmpeg -y

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

echo "CodeFormer 环境搭建完成！"

Windows 注意事项

Git 仓库路径

Windows 的文件路径长度有限制（MAX_PATH=260）。把 CodeFormer 仓库放在短路径下：

• ✅ D:\CodeFormer
• ❌ C:\Users\你的用户名\Desktop\AI\Projects\FaceRestoration\CodeFormer

Visual C++ Redistributable

某些依赖（如 dlib）需要 Visual C++ 运行时，确保装了 [Microsoft Visual C++ Redistributable](<URL>

管理员权限

如果 pip install 报权限错误，试试在管理员权限的 PowerShell 里跑。

环境验证脚本

搭完环境后，用这几行确认一切正常：

# verify_env.py
import torch
print(f"PyTorch: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU: {torch.cuda.get_device_name(0)}")
    print(f"VRAM: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB")

import basicsr
print(f"BasicSR: OK")

import facexlib
print(f"facexlib: OK")

import dlib
print(f"dlib: OK")

如果每个 import 都不报 ModuleNotFoundError，环境就搭好了。