dlib 安装失败排查：Windows / Linux 两条路各 3 分钟搞定

先评估：要不要装 dlib

dlib 是 可选的人脸检测器，CodeFormer 默认用 YOLOv5-face（通过 facexlib）。如果你用 CodeFormer 的主流程（整图自动检测修复），不装 dlib 也能跑。

什么时候必须装 dlib：

• 用 scripts/crop_align_face.py 批量裁脸对齐（YOLOv5-face 也能用，但 dlib 的 68 点 landmark 更精细）
• 视频处理中需要精确的 landmark 对齐

如果只是跑推理脚本，跳过这页——你不需要 dlib。

方案一：Conda（最推荐，99% 成功率）

conda activate codeformer
conda install -c conda-forge dlib

Conda-forge 提供了预编译 wheel，不需要 CMake、不需要 VS Build Tools。Linux/Mac/Windows 全支持。

如果 conda-forge 没有你 Python 版本的包

# 查看 conda-forge 有哪些 dlib 版本
conda search -c conda-forge dlib

# 如果没有，创建环境时指定 Python 3.8（兼容性最好）
conda create -n codeformer python=3.8 -y
conda install -c conda-forge dlib

方案二：pip 预编译 wheel

conda-forge 不行再试 pip 预编译 wheel。

Windows

去 Gohlke 的 dlib wheel 集合下载对应你 Python 版本和位数的 .whl：

• 文件名形如 dlib-19.24.0-cp38-cp38-win_amd64.whl
• cp38 = Python 3.8，win_amd64 = Windows 64 位

下载后：

pip install dlib-19.24.0-cp38-cp38-win_amd64.whl

Linux / Mac

pip install dlib

现代 Linux 发行版（Ubuntu 20.04+）和 macOS（Apple Silicon）上，pip 也能直接装成功（前提是装了 build-essential）。

方案三：源码编译（最后手段）

如果 Conda 和 pip wheel 都不行，只能源码编译。

Windows 前置条件

1. CMake ≥ 3.18：cmake.org/download，下载 msi 装
2. Visual Studio Build Tools 2022：安装器里选 "C++ 桌面开发" 组件
3. boost（可选，某些 dlib 模块需要）

编译命令

git clone -b v19.24.0 <URL>
cd dlib
python setup.py install --set DLIB_USE_CUDA=OFF --set CMAKE_BUILD_TYPE=Release

常见编译错误

安装验证

import dlib
print(f"dlib 版本: {dlib.__version__}")

# 测试人脸检测器
detector = dlib.get_frontal_face_detector()
# 再导入 facexlib 确保 CodeFormer 能正常调用 face detection
from facexlib.detection import init_detection_model
print("OK")

放弃 dlib 的替代方案

装了半小时还没成功？直接放弃——CodeFormer 默认的 YOLOv5-face 检测器也能做人脸检测和对齐，精度不输 dlib：

# YOLOv5-face 检测（通过 facexlib）
from facexlib.detection import init_detection_model, get_face_coords, draw_face_kps
from facexlib.utils.face_restoration_helper import FaceRestoreHelper

# 初始化检测器
detector = init_detection_model('yolov5n', half=False, device='cuda')

# CodeFormer 整图模式就是用的这个，不需要手动调用 dlib

dlib 唯一比 YOLOv5-face 强的是 68 点 landmark 精细对齐——但对大多数人脸修复场景，5 点 landmark（YOLOv5 的精度）已经足够。

总结

1. 先确认要不要装 dlib（大概率不需要）
2. 需要装 → Conda 一行命令
3. Conda 不行 → pip 预编译 wheel
4. wheel 不行 → 源码编译
5. 源码编译还不行 → 放弃 dlib，用 YOLOv5-face