【BUG已解决】pip install 出现 error: Microsoft Visual C 14.0 or greater is required 解决方案1. 问题描述在 Windows 上使用 pip 安装某些包尤其是包含 C/C 扩展的库如 numpy 老版本、某些冷门库、需要本地编译的包时报错 pip install some-package 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/有时候错误信息会稍有不同但核心都是提示缺少编译工具error: Microsoft Visual C is required. Get it from https://visualstudio.microsoft.com/downloads/这个报错专属于 Windows 平台——因为大多数 Python 包在 PyPI 上会预先编译好 Windows 的 wheel.whl二进制文件但少数包尤其小众库或较老的版本只提供源码包.tar.gz安装时需要在本机现场编译 C 扩展代码而 Windows 默认并不自带 C 编译器。2. 原因分析pip install 某个包 ↓ PyPI 上该包没有对应 Python 版本/系统架构 的预编译 wheel ↓ pip 退回到下载源码包尝试本地编译 ↓ 本地编译需要调用 C 编译器cl.exe属于Visual Studio套件 ↓ Windows未安装该编译器 → 报错版本号对应的 Visual Studio 版本MSVC 14.0Visual Studio 2015/2017/2019/202214.0是ABI版本号2015后长期保持兼容3. 解决方案方案一安装 Microsoft C Build Tools推荐只装编译器不装完整IDE无需安装完整的 Visual Studio只需要安装其中的生成工具组件访问 Visual Studio Build Tools 下载页下载并运行安装器在组件选择界面勾选使用 C 的桌面开发Desktop development with C确保右侧至少勾选MSVC v143 - VS 2022 C x64/x86 生成工具Windows 10/11 SDK点击安装体积约 3-6GB视勾选组件而定安装完成后重新打开终端重要需要让新的环境变量生效pip install some-package方案二优先寻找预编译好的 wheel 包避免本地编译很多包即使官方PyPI没有预编译wheel社区维护者也会提供第三方预编译包# 【BUG已解决】查看PyPI页面是否真的没有Windows wheel # https://pypi.org/project/包名/#files # 部分老牌库可以从Christoph Gohlke维护的非官方wheel库下载历史资源现已归档但仍可用 # https://www.lfd.uci.edu/~gohlke/pythonlibs/ # 或者优先尝试用conda安装conda生态对Windows预编译支持更好 conda install some-package方案三使用 conda 代替 pip 安装规避编译问题的有效途径conda 的软件仓库对 Windows 平台预编译支持通常比 PyPI 更完善尤其是科学计算类库conda install -c conda-forge some-package方案四确认是否真的需要该库的最新版本有些老旧库版本要求编译但升级到新版本后可能已经提供了预编译wheelpip install --upgrade some-package # 或者查看该库各版本发布记录找到有wheel支持的版本 pip index versions some-package方案五使用 WSL2终极规避方案如果不想在 Windows 上折腾 C 编译环境直接在 WSL2 的 Linux 子系统中进行 Python 开发Linux 环境的编译工具链天然齐全# 在WSL2 Ubuntu中 sudo apt update sudo apt install build-essential python3-dev pip install some-package方案六仅需要特定编译器组件时的精简安装如果不想下载几个GB的完整Build Tools可以尝试仅安装必需的最小组件适合网络环境不佳、磁盘空间有限的场景# 使用离线安装器的命令行参数仅安装C工作负载需先下载vs_buildtools.exe vs_buildtools.exe --quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.Windows10SDK.190414. 各方案对比总结方案磁盘占用适用场景推荐指数安装Build Tools3-6GB长期Windows Python开发⭐⭐⭐⭐⭐寻找预编译wheel无额外占用只是想快速装上某个包⭐⭐⭐⭐⭐用conda安装视包而定已经在用conda环境⭐⭐⭐⭐⭐升级到新版本无额外占用库本身有更新的预编译版本⭐⭐⭐⭐使用WSL2需要额外配置Linux子系统频繁遇到Windows编译问题⭐⭐⭐⭐5. 常见问题 FAQ5.1 安装了Build Tools后仍然报错# 确认是否重新打开了新的终端窗口环境变量PATH需要重新加载 # 关闭所有已打开的cmd/PowerShell/VSCode终端重新打开 # 验证cl.exe是否可用 where cl如果where cl找不到可能需要使用 Developer Command Prompt for VS 而不是普通终端开始菜单 → 搜索 x64 Native Tools Command Prompt → 在此终端中运行 pip install5.2 如何确认某个包是否需要编译# 查看PyPI该包的Files页面如果只有.tar.gz没有.whl说明该版本没有预编译包 # 或者直接尝试安装观察报错信息中是否提及编译相关内容 pip install --no-binary :all: some-package # 强制走源码编译路径进行测试5.3 Python 版本与预编译wheel的对应关系预编译wheel通常按 Python 版本如 cp310 代表 CPython 3.10和系统架构win_amd64命名numpy-1.26.0-cp310-cp310-win_amd64.whl ↑ ↑ ↑ 版本号 Python版本 系统架构如果你的 Python 版本太新比如刚发布的 3.13某些包可能还没来得及为该版本发布预编译wheel这时只能等待官方更新或本地编译。5.4 企业内网无法访问微软官方下载站怎么办# 可以联系IT部门获取离线安装包 # 或使用国内镜像加速下载部分云盘/镜像站会转存VS Build Tools安装包 # 另一个思路申请一台能访问外网的机器下载后拷贝到内网使用5.5 M1/M2 MacARM架构是否也会遇到类似问题Mac 上对应的报错通常是缺少 Xcode Command Line Toolsxcode-select --install原理相同——都是缺少本地C/C编译环境只是不同平台需要安装的工具链不同。5.6 Docker容器内构建镜像时如何避免此问题在 Dockerfile 中提前安装好编译依赖FROM python:3.11-slim # Debian/Ubuntu基础镜像需要手动安装build-essential RUN apt-get update apt-get install -y build-essential COPY requirements.txt . RUN pip install -r requirements.txt5.7 如何判断安装失败的根本原因是缺少编译器还是缺少SDK头文件有时候即使装了 Build Tools仍然报类似但更具体的错误如缺少特定的 Windows SDK 头文件fatal error C1083: Cannot open include file: basetsd.h: No such file or directory在Visual Studio Installer中确认已勾选对应版本的Windows SDK Individual components → Windows 10 SDK (或 Windows 11 SDK取决于系统版本)5.8 特定科学计算库如scipy、scikit-learn的官方预编译渠道推荐对于常见的科学计算库官方通常提供更可靠的安装渠道避免走本地编译路径# scipy生态推荐优先使用conda-forge渠道预编译覆盖更全面 conda install -c conda-forge scipy scikit-learn numpy pandas # 或者使用官方推荐的清华源加速下载已有的预编译wheel pip install scipy -i https://pypi.tuna.tsinghua.edu.cn/simple5.9 GitHub Actions等云端CI环境中如何配置Windows编译环境# GitHub Actions Windows Runner 通常已经预装了必要的编译工具 runs-on: windows-latest steps: - uses: actions/checkoutv4 - name: Set up MSVC uses: microsoft/setup-msbuildv2 - name: Install dependencies run: pip install -r requirements.txtGitHub 官方的windows-latest镜像默认已包含 Visual Studio Build Tools通常不需要额外配置就能正常编译。5.10 排查是否是32位/64位架构不匹配导致的连带问题# 确认Python本身是32位还是64位版本 python -c import platform; print(platform.architecture()) # 确认安装的Build Tools组件是否包含对应架构的编译目标 # 现代Python基本都是64位确保勾选了 MSVC v143 - VS 2022 C x64/x86 生成工具5.11 团队标准化开发机镜像的长期方案对于经常需要给新员工配置开发环境的团队建议制作标准化的开发机镜像Windows可用Packer/云厂商镜像模板预装好Build Tools等常用组件# 使用Chocolatey等包管理器批量安装标准工具链减少手动操作 choco install visualstudio2022buildtools -y choco install python312 -y choco install git -y新员工拿到预装好的开发机镜像后几乎不会再遇到本文讨论的编译环境问题。5.11.1 补充ARM架构Windows设备如Surface Pro X的特殊兼容性问题ARM架构的Windows设备在处理需要本地编译的Python包时可能遇到比x86更复杂的兼容性问题因为部分第三方库尚未提供ARM64版本的预编译wheel# 检查当前系统架构 python -c import platform; print(platform.machine()) # ARM64设备遇到编译问题时优先考虑使用x64模拟层运行Python而非在原生ARM64环境中编译5.11.2 补充GitHub Actions self-hosted Windows Runner的环境准备如果团队使用自建的Windows CI Runner而非GitHub官方托管Runner需要手动确保Build Tools已预装否则每次CI构建都会重现本文讨论的问题# 在自建Runner的初始化脚本中提前安装好Build Tools choco install visualstudio2022buildtools --package-parameters --add Microsoft.VisualStudio.Workload.VCTools -y5.11.3 补充Rust编写的Python扩展库(如某些新版加密库)的额外要求部分现代Python库底层用Rust编写扩展模块遇到编译问题时除了C编译器还可能需要Rust工具链# 安装Rust编译工具链 winget install Rustlang.Rustup # 重启终端后验证 rustc --version pip install some-rust-based-package5.11.4 补充企业镜像分发系统中预置Build Tools的规模化方案大型企业IT部门可通过SCCM等软件分发系统批量将Build Tools推送到所有Windows开发机无需每个开发者手动下载安装显著提升团队整体的环境搭建效率。6. 排查清单速查表□ 1. 确认报错的包名查看PyPI是否有对应Windows wheel □ 2. 尝试用conda安装同一个包 □ 3. 尝试升级到该库的最新版本 □ 4. 下载安装 Visual Studio Build Tools勾选使用C的桌面开发 □ 5. 安装完成后重新打开终端再试 □ 6. 长期在Windows做Python开发的建议一次性装好Build Tools备用 □ 7. 频繁遇到编译问题考虑迁移到WSL2开发环境7. 总结Microsoft Visual C 14.0 or greater is required的核心是Windows 缺少本地 C/C 编译器而目标包需要在本机编译。解决优先级先看是否有捷径——换用conda安装、升级到有预编译wheel的新版本长期开发者——一次性装好 Visual Studio Build Tools仅C桌面开发组件一劳永逸频繁踩坑者——考虑转到 WSL2 或 Linux 环境做 Python 开发从根本上规避 Windows 编译生态的种种限制建议团队在 Windows 开发机的标准环境配置文档中直接把 Build Tools 安装作为必装项写入避免每个新成员都要单独排查一次这个经典问题。