Windows10中pip install -r requirements.txt安装失败，hnswlib编译报错

问题 #

在Windows10环境下执行pip install -r requirements.txt安装依赖时失败，已下载Microsoft C++ Build Tools但问题依旧，尝试修改命令为pip install [User] -r requirements.txt也无效，具体报错如下：

Building wheels for collected packages: hnswlib
  Building wheel for hnswlib (pyproject.toml) ... error
  error: subprocess-exited-with-error

  × Building wheel for hnswlib (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [5 lines of output]
      running bdist_wheel
      running build
      running build_ext
      building 'hnswlib' extension
      error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for hnswlib
Failed to build hnswlib
ERROR: Could not build wheels for hnswlib, which is required to install pyproject.toml-based projects

原因分析 #

• 仅安装Microsoft C++ Build Tools主程序不够，未勾选编译hnswlib所需的核心组件，系统无法识别到合格的C++编译环境。
• pip install [User] -r requirements.txt是错误命令，[User]不属于pip合法参数，完全无效。
• hnswlib包含C++扩展模块，需要本地编译生成wheel，但当前编译环境配置不完整，导致构建失败。

解决方法 #

方法1：补全C++ Build Tools组件 #

1. 打开已安装的Microsoft C++ Build Tools，选择「修改」。
2. 在工作负载列表中勾选**「使用C++的桌面开发」**，确保勾选以下核心组件：
   • MSVC v142或更高版本的编译器工具集
   • 对应Windows10版本的Windows SDK
   • C++ CMake工具（可选，推荐安装）
3. 点击「修改」完成组件安装，重启电脑后重新执行安装命令。

方法2：安装预编译的hnswlib轮子（快速解决） #

直接安装PyPI上的预编译版本，跳过本地编译步骤：

pip install hnswlib --only-binary :all:

完成后再执行原依赖安装命令：

pip install -r requirements.txt

方法3：验证编译环境配置 #

• 打开命令提示符，输入cl命令，如果能输出MSVC编译器版本信息，说明环境配置成功；若提示「找不到命令」，需手动将MSVC的bin目录（一般在C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\版本号\bin\Hostx64\x64）添加到系统PATH中。
• 确保Python版本（建议3.7及以上）与MSVC工具集版本兼容，比如Python 3.9+推荐搭配MSVC v142及以上版本。

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