M1 Pro芯片macOS系统安装PyQtWebEngine报错解决方法

问题现象 #

在搭载M1 Pro芯片的macOS设备上执行pip安装PyQtWebEngine时出现构建报错，核心错误为元数据生成失败，报错关键信息如下：

File "/private/var/folders/52/qg4pw1dj73j4t7s079kckmz80000gn/T/pip-build-env-o6asbq8b/overlay/lib/python3.9/site-packages/pyqtbuild/builder.py", line 67, in apply_user_defaults
          raise PyProjectOptionException('qmake',
      sipbuild.pyproject.PyProjectOptionException

error: metadata-generation-failed

参照公开issue中的步骤操作后依旧无法完成安装。

报错根因 #

• PyPI官方源上PyQtWebEngine 5.15.6版本没有提供适配Apple Silicon（arm64）架构的预编译安装包，pip默认拉取源码包在本地编译
• 本地编译阶段找不到匹配版本的qmake构建工具，同时临时构建环境里的sip、pyqtbuild依赖版本不兼容，直接触发构建失败
• 网上流传的旧方案大多针对x86架构Intel芯片Mac，没有适配M系列芯片的架构差异，操作后依旧会报错

可直接落地的安装方案 #

按成功率从高到低排序：

• 方案1：通过conda安装（零编译，成功率最高）
  激活目标Python虚拟环境后，直接执行命令：
  conda install pyqtwebengine
  conda会自动匹配适配M1 Pro arm64架构的预编译包，自动处理qmake、sip等所有依赖，不需要手动改配置，执行完即可正常使用。

• 方案2：Homebrew + pip组合安装（不用conda的场景选这个）

  1. 先通过Homebrew安装Qt5、PyQt5和PyQtWebEngine的系统级依赖，自动适配arm64架构：
     brew install qt@5 pyqt@5 pyqtwebengine@5
  2. 提前在虚拟环境里安装匹配版本的构建依赖，避免pip拉取不兼容的临时版本：
     pip install sip PyQt5 PyQt5-sip pyqtbuild
  3. 指定Homebrew安装的qmake路径，跳过构建隔离执行安装：
     pip install --no-build-isolation PyQtWebEngine --config-settings=--qmake=/opt/homebrew/opt/qt@5/bin/qmake

避坑注意事项 #

• 安装前先确认当前Python环境是原生arm64版本，执行python -c "import platform; print(platform.machine())"，输出arm64才符合要求；如果输出x86_64说明装的是Rosetta转译的Python，会出现架构不匹配问题，先换成arm64版本的Python再操作
• 如果之前有安装失败的残留包，先执行pip uninstall -y PyQtWebEngine PyQt5 sip pyqtbuild清理干净残留再重新安装
• 不要直接执行裸的pip install PyQtWebEngine命令，这个操作默认拉源码编译，在M系列芯片Mac上基本都会失败

内容的提问来源于stack exchange，提问作者xin.chen