Python安装dlib过程中出现setup.py报错的解决方案咨询

报错根因梳理 #

三类报错分别对应独立问题，无交叉关联：

• 安装初始的PyPI连接超时为网络问题，官方源访问不稳定会导致拉包中断，甚至生成残缺的本地缓存安装包
• 构建阶段提示ERROR: CMake must be installed to build dlib并非未安装CMake，而是CMake路径未加入系统环境变量，构建进程无法调用CMake程序；同时未安装wheel组件会导致pip自动走legacy模式的setup.py源码构建流程，提升构建失败概率；本地缓存的3.2MB版本dlib源码包存在文件缺失，才会触发dlib__init__.py not found的提示
• 执行install wheel返回命令不存在属于语法错误，所有pip包管理操作必须以pip作为命令开头，直接输入install系统无法识别对应指令

分步操作流程 #

按顺序执行以下操作，每步完成验证通过后再进入下一步：

1. 基础依赖配置校验
   • 新开命令提示符窗口，执行pip --version确认pip可用，若设备存在多Python环境（多版本Python、Anaconda与官方Python共存），执行where pip确认返回的pip路径和日常使用的Python路径匹配，避免包装到其他环境
   • 执行pip install wheel完成wheel组件安装
   • 执行cmake --version验证CMake是否可被命令行识别，若返回“不是内部或外部命令”，找到本机CMake安装目录下的bin文件夹（默认路径为C:\Program Files\CMake\bin），将该路径添加到系统环境变量Path中，关闭所有已打开的命令提示符窗口重新打开，再次执行cmake --version，确认能正常输出版本号即配置完成
   • 执行pip cache purge清除本地pip缓存，删除之前下载的残缺dlib安装包
2. 执行dlib安装
   执行带参数的安装命令规避超时、缓存问题：
   pip install dlib --no-cache-dir -i 可正常访问的国内PyPI镜像地址
   替换命令中的镜像地址部分为可用的国内PyPI镜像，即可解决官方源连接超时问题
3. 构建失败兜底方案
   如果上述操作后仍触发源码构建错误，先打开Visual Studio Installer，确认已安装「使用C++的桌面开发」组件，且勾选了对应版本的Windows SDK、MSVC生成工具；若不想手动排查编译组件问题，可直接下载和当前Python版本、系统位数匹配的dlib预编译wheel包，本地执行pip install 下载的wheel包本地路径即可跳过源码编译流程完成安装。

注意：修改系统环境变量、安装依赖后必须重启命令提示符窗口，旧窗口不会加载更新后的环境变量配置，会导致后续命令执行失败。

内容的提问来源于stack exchange，提问作者Mahdiath Hasan