DLib

机器学习和计算机视觉工具包

人脸识别 机器学习 计算机视觉 C++
官网 GitHub PyPI

DLib 是现代 C++ 工具包，特别擅长人脸检测、人脸识别、特征点定位等任务。

安装

运行以下命令安装：
pip install dlib
💡 提示：建议在虚拟环境中安装，避免依赖冲突。

抠头助手安装

使用抠头助手一键安装 DLib，自动处理依赖、镜像加速、环境隔离，告别繁琐配置。

1 下载抠头助手
占位图：下载抠头助手

访问官网下载最新版本

2 搜索库
占位图：搜索库

在搜索框输入库名称

3 一键安装
占位图：一键安装

点击安装按钮，等待完成

常见问题

CMake must be installed to build the following extensions: dlib 在通过 pip 从源码安装 dlib 时，系统缺少 CMake 构建工具。
▼
1 Windows：下载并安装 Visual Studio Build Tools，确保安装‘使用 C++ 的桌面开发’工作负载，或单独安装 CMake 并将其添加到 PATH。
2 Ubuntu/Debian：在终端运行 `sudo apt-get install cmake`。
3 macOS：使用 Homebrew 安装，运行 `brew install cmake`。
4 如果已安装 CMake 但版本太旧，请升级至较新版本（如 3.8 或更高）。
Failed to compile dlib: No such file or directory: 'boost/python.hpp' 编译 dlib 时找不到 Boost.Python 库，这是一个常见依赖。
▼
1 Ubuntu/Debian：安装 libboost-python-dev，运行 `sudo apt-get install libboost-python-dev`。
2 Windows：从 Boost 官网下载预编译库或使用源代码编译，并确保环境变量 BOOST_ROOT 和 BOOST_LIBRARYDIR 正确设置。
3 macOS：使用 Homebrew 安装，运行 `brew install boost-python3`（或 boost-python，取决于 Python 版本）。
4 作为最后手段，可以使用预编译的 dlib wheel 文件，避免从源码编译。
ImportError: DLL load failed while importing dlib: The specified module could not be found 在 Windows 上导入 dlib 时，缺少必要的运行时 DLL（通常是 Visual C++ Redistributable 或 CUDA 相关 DLL）。
▼
1 确保已安装 Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017, 2019 and 2022（x64 版本）。
2 如果安装了支持 CUDA 的 dlib 版本，请确保正确安装了对应版本的 CUDA Toolkit 和 cuDNN，并将它们的 `bin` 目录（如 `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin`）添加到系统 PATH 环境变量中。
3 尝试使用纯 CPU 版本的 dlib。通过 `pip install dlib==19.22`（较旧纯CPU版本）或寻找标记为“仅CPU”的较新 wheel 文件。
RuntimeError: Error while calling cudaGetDevice(&the_device_id) in file …\dlib\cuda\cuda_dlib.cu:193. code: 35, reason: CUDA driver version is insufficient for CUDA runtime version CUDA 运行时版本与系统 NVIDIA 显卡驱动版本不兼容。
▼
1 更新你的 NVIDIA 显卡驱动到最新版本，或至少匹配你安装的 CUDA Toolkit 版本所要求的最低驱动版本。
2 访问 NVIDIA 官网下载或使用 GeForce Experience 更新驱动。
3 降级 dlib 或 CUDA Toolkit 版本以匹配旧的显卡驱动（不推荐）。
4 如果无需GPU加速，可安装或重新编译纯CPU版本的dlib。
AttributeError: module 'dlib' has no attribute 'get_frontal_face_detector' or 'shape_predictor' 通常发生在安装了错误版本的 dlib（例如，一个被重命名或非官方的、功能不全的包），或者导入的模块名与文件冲突。
▼
1 确认安装的是官方 dlib 包：`pip list | findstr dlib` 或 `pip show dlib`。
2 如果存在命名冲突（例如，你有一个名为 `dlib.py` 的本地文件），请重命名该文件。
3 完全卸载并重新安装官方版本：`pip uninstall dlib -y`，然后 `pip install dlib`。
4 对于特定功能缺失，确保安装的 dlib 版本足够新（例如，`shape_predictor` 需要较新版本）。
pip install dlib 编译失败，报错： Unable to find vcvarsall.bat / Microsoft Visual C++ 14.0 or greater is required 在 Windows 上从源码编译 Python 扩展时，缺少 Microsoft Visual C++ 构建工具。
▼
1 安装 Visual Studio Build Tools（2022 版等），并勾选‘使用 C++ 的桌面开发’工作负载。
2 或者，安装较旧但专门的 Microsoft Build Tools for Visual Studio 2019。
3 更简单的方案：安装预编译的 wheel 文件。访问 Christoph Gohlke 的非官方 Windows 二进制库页面，下载对应你 Python 版本和系统架构（如 cp39-win_amd64）的 dlib .whl 文件，然后通过 `pip install 下载的文件名.whl` 安装。
MemoryError 或进程在训练/预测时被杀死 (Killed) 通常在 Linux/macOS 上使用大量内存时发生，系统因内存不足而终止进程。
▼
1 增加系统的交换空间（Swap Space）。在 Linux 上，可以使用 `sudo fallocate -l 4G /swapfile` 等命令创建交换文件。
2 减少批处理大小（batch size）或使用更小的模型。
3 确保使用的是 64 位 Python 解释器，并能访问足够的内存。
4 如果使用形状预测器训练，考虑使用 `--oversampling` 和 `--nu` 参数来降低内存需求。
RuntimeError: dlib: Incompatible library version. dlib requires version X.X.X or later but Y.Y.Y is found 在 macOS 上，动态链接器发现了不兼容的系统库版本（如 libjpeg, libpng）。
▼
1 使用 Homebrew 重新安装或更新相关库：`brew update && brew upgrade`。
2 强制链接特定库：`brew link --force libjpeg libpng`（谨慎使用）。
3 在虚拟环境中使用 `conda` 安装 dlib：`conda install -c conda-forge dlib`，这可以更好地管理依赖。
4 通过 `pip install dlib --no-binary dlib` 从源码重新编译 dlib，使其链接到正确版本的库。
ERROR: Failed building wheel for dlib 这是一个通用错误，表明编译 dlib 的 wheel 包失败。根本原因通常是缺少依赖（CMake、C++编译器、Boost等）或环境问题。
▼
1 首先，仔细阅读错误输出，寻找更具体的错误信息（如关于 CMake、Boost 或特定文件的错误）。
2 确保已安装所有必需的依赖项（C++ 编译器、CMake、Boost.Python）。
3 尝试升级 pip、setuptools 和 wheel：`pip install --upgrade pip setuptools wheel`。
4 如果使用 Windows，确保在“Visual Studio Developer Command Prompt”或安装了完整构建工具的环境下运行 pip 命令。
5 考虑使用预编译的二进制文件（wheel）以避免编译。
ImportError: cannot import name 'cnn_face_detection_model_v1' from 'dlib' 尝试导入的 CNN 人脸检测模型在已安装的 dlib 版本中不存在或名称有误。
▼
1 确认你的 dlib 版本。CNN 人脸检测器在较新版本中可用。使用 `dlib.__version__` 检查。
2 升级 dlib 到最新版本：`pip install --upgrade dlib`。
3 检查导入语句是否正确。正确导入方式为：`from dlib import cnn_face_detection_model_v1`，或先 `import dlib`，再使用 `dlib.cnn_face_detection_model_v1`。
4 如果无法升级，请根据你的 dlib 版本查阅对应文档，使用正确的函数或类名。
CUDA out of memory (RuntimeError when using dlib with CUDA) 使用 dlib 的 GPU/CUDA 功能时，显卡显存不足，无法处理当前数据量。
▼
1 减少批处理大小（batch size）。
2 缩小输入图像的尺寸。
3 关闭其他占用显存的程序（如其他深度学习任务、游戏）。
4 使用 `nvidia-smi` 命令查看显存占用情况，并尝试终止无关进程（使用 `kill -9 PID`）。
5 如果模型支持，尝试使用 CPU 模式运行（如果 dlib 编译时支持切换）。
TypeError: __init__() got an unexpected keyword argument 'model' 在使用 `dlib.shape_predictor` 或类似函数时，传递了错误的参数名，常见于 API 变更或代码示例版本不匹配。
▼
1 查阅你当前安装的 dlib 版本的官方文档或 docstring（如 `help(dlib.shape_predictor)`）。
2 通常，`shape_predictor` 的构造函数只需要模型文件路径。正确用法：`predictor = dlib.shape_predictor("shape_predictor_68_face_landmarks.dat")`。
3 确保你下载的预训练模型文件与 dlib 版本兼容。
4 检查并修正你的代码，移除错误的参数（如 `model=`）。
冲突：同时安装 dlib 和 face-recognition 等包时的依赖问题 face-recognition 等包对 dlib 有特定版本要求，可能导致与已安装的 dlib 版本冲突。
▼
1 为项目创建独立的虚拟环境（venv 或 conda）。
2 在干净的环境中，先安装 dlib，再安装 face-recognition：`pip install dlib` 然后 `pip install face-recognition`。
3 如果 face-recognition 安装失败，可以尝试安装其特定版本或从源码安装，让它自动处理 dlib 依赖：`pip install git+https://github.com/ageitgey/face_recognition.git`。
4 使用 conda 可以更好地解决依赖：`conda install -c conda-forge face-recognition`，它会自动处理 dlib 依赖。
无法在 Apple Silicon (M1/M2) Mac 上安装或导入 dlib 原生的 dlib wheel 可能不兼容 ARM 架构的 macOS，导致安装失败或导入崩溃。
▼
1 通过 Miniforge 或 Anaconda 使用 conda 安装：`conda install -c conda-forge dlib`，conda-forge 提供原生 ARM 版本。
2 如果使用 pip，确保使用 Rosetta 2 的 Intel 版本 Python 环境，并通过 `pip install dlib` 安装 x86_64 版本的 wheel。
3 从源码编译：确保已安装 Xcode Command Line Tools 和 CMake，然后使用 `pip install dlib --no-binary dlib`。
4 对于原生 ARM Python，可以尝试寻找或自行构建支持 arm64 的 wheel 文件。

🛠️ 还是搞不定？ 下载抠头助手，一键解决所有安装问题！

ℹ️ 需要更多帮助？