Mac pip安装numpy报错：Building wheel for numpy构建失败

报错根因 #

• 触发subprocess-exited-with-error（退出码1）、Failed building wheel for numpy报错的核心是本地编译依赖缺失：
  • 系统未预装gfortranFortran编译器，无法编译numpy源码中的Fortran模块
  • 当前Python环境缺失开发头文件Python.h，Mac端无单独的python-dev/python-devel分发包，头文件随XCode命令行工具或完整Python安装包自带
• Windows端相同操作无异常是因为平台提供了全版本numpy预编译wheel包，安装时不需要走本地源码编译流程，不会触发依赖校验。

修复步骤 #

1. 安装基础编译依赖
   打开终端依次执行以下命令：

# 安装XCode命令行工具，自带C编译链、Python开发头文件
xcode-select --install
# 通过Homebrew安装gcc套件，内置所需的gfortran编译器
brew install gcc

执行xcode-select --install后会弹出系统安装引导，按提示完成安装后重启终端再操作即可。如果未安装Homebrew，也可手动下载对应Mac芯片架构（Intel/Apple Silicon）的gfortran安装包部署，注意版本需和当前系统大版本匹配。

2. 校验依赖可用性
   终端执行以下命令确认依赖安装正常：

# 校验gfortran是否部署成功，正常执行会输出版本信息
gfortran --version
# 输出Python头文件存储路径
python3 -c "import sysconfig; print(sysconfig.get_path('include'))"

打开第二条命令输出的文件夹路径，确认路径下存在Python.h文件即可。如果路径下无该文件，说明当前使用的是系统自带裁剪版Python或第三方精简版Python，直接下载对应版本的官方完整Python安装包重装即可。

3. 升级构建工具后重装numpy
   先升级pip相关构建组件，避免旧版本工具无法识别适配当前系统的预编译包：

pip install --upgrade pip setuptools wheel
pip install numpy

兜底方案 #

如果上述操作后仍触发源码编译流程报错，可执行命令强制拉取预编译二进制包安装，跳过本地编译步骤：

pip install --only-binary=:all: numpy

注意：使用Apple Silicon（M1/M2/M3系列）芯片的Mac设备，不要用Rosetta转译模式运行终端，直接使用系统原生终端执行命令，避免架构不匹配导致预编译包拉取失败，强制触发本地编译流程。

内容的提问来源于stack exchange，提问作者Cường Phan Quốc