树莓派安装PyQt6报错：sipbuild.api属性缺失及元数据生成失败

环境信息 #

• 系统：Raspbian GNU/Linux 11 (bullseye) 32位
• 内核：5.15.61-v7+
• Python版本：3.9.2
• 硬件：树莓派3 Model B Rev 1.2 / 树莓派4 Model B

报错详情 #

1. pip 20.3.4版本下的初始报错 #

执行pip install PyQt6时出现核心错误：

AttributeError: module 'sipbuild.api' has no attribute 'prepare_metadata_for_build_wheel'

完整报错日志：

Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Collecting PyQt6
  Using cached PyQt6-6.4.2.tar.gz (1.0 MB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... error
    ERROR: Command errored out with exit status 1:
     command: /usr/bin/python3 /tmp/tmpg8vbytn0_in_process.py prepare_metadata_for_build_wheel /tmp/tmpibnxfxlu
         cwd: /tmp/pip-install-ahxh_8fa/pyqt6_64f704c0d362442abcae9385cfcd89c0
    Complete output (31 lines):
    Traceback (most recent call last):
      File "/tmp/tmpg8vbytn0_in_process.py", line 126, in prepare_metadata_for_build_wheel
        hook = backend.prepare_metadata_for_build_wheel
    AttributeError: module 'sipbuild.api' has no attribute 'prepare_metadata_for_build_wheel'
    
    During handling of the above exception, another exception occurred:
    
    Traceback (most recent call last):
      File "/tmp/tmpg8vbytn0_in_process.py", line 280, in <module>
        main()
      File "/tmp/tmpg8vbytn0_in_process.py", line 263, in main
        json_out['return_val'] = hook(**hook_input['kwargs'])
      File "/tmp/tmpg8vbytn0_in_process.py", line 130, in prepare_metadata_for_build_wheel
        return _get_wheel_metadata_from_wheel(backend, metadata_directory,
      File "/tmp/tmpg8vbytn0_in_process.py", line 159, in _get_wheel_metadata_from_wheel
        whl_basename = backend.build_wheel(metadata_directory, config_settings)
      File "/tmp/pip-build-env-5i1i4ta7/overlay/lib/python3.9/site-packages/sipbuild/api.py", line 46, in build_wheel
        project = AbstractProject.bootstrap('wheel',
      File "/tmp/pip-build-env-5i1i4ta7/overlay/lib/python3.9/site-packages/sipbuild/abstract_project.py", line 87, in bootstrap
        project.setup(pyproject, tool, tool_description)
      File "/tmp/pip-build-env-5i1i4ta7/overlay/lib/python3.9/site-packages/sipbuild/project.py", line 585, in setup
        self.apply_user_defaults(tool)
      File "project.py", line 65, in apply_user_defaults
        super().apply_user_defaults(tool)
      File "/tmp/pip-build-env-5i1i4ta7/overlay/lib/python3.9/site-packages/pyqtbuild/project.py", line 70, in apply_user_defaults
        super().apply_user_defaults(tool)
      File "/tmp/pip-build-env-5i1i4ta7/overlay/lib/python3.9/site-packages/sipbuild/project.py", line 236, in apply_user_defaults
        self.builder.apply_user_defaults(tool)
      File "/tmp/pip-build-env-5i1i4ta7/overlay/lib/python3.9/site-packages/pyqtbuild/builder.py", line 69, in apply_user_defaults
        raise PyProjectOptionException('qmake',
    sipbuild.pyproject.PyProjectOptionException
    ----------------------------------------
WARNING: Discarding https://files.pythonhosted.org/packages/c3/e0/e1b592a6253712721612e2e64a323930a724e1f5cf297ed5ec6d6c86dda1/PyQt6-6.4.2.tar.gz#sha256=740244f608fe15ee1d89695c43f31a14caeca41c4f02ac36c86dfba4a5d5813d (from https://pypi.org/simple/pyqt6/) (requires-python:>=3.6.1). Command errored out with exit status 1: /usr/bin/python3 /tmp/tmpg8vbytn0_in_process.py prepare_metadata_for_build_wheel /tmp/tmpibnxfxlu Check the logs for full command output

2. 升级pip到23.0.1后报错 #

升级pip后执行安装，出现核心提示：

Preparing metadata (pyproject.toml) did not run successfully.

完整报错信息：

Defaulting to user installation because normal site-packages is not writeable
Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Collecting PyQt6
  Using cached PyQt6-6.4.2.tar.gz (1.0 MB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Preparing metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [22 lines of output]
      Traceback (most recent call last):
        File "/usr/local/lib/python3.9/dist-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/usr/local/lib/python3.9/dist-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
        File "/usr/local/lib/python3.9/dist-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 152, in prepare_metadata_for_build_wheel
          whl_basename = backend.build_wheel(metadata_directory, config_settings)
        File "/tmp/pip-build-env-rtbrazp0/overlay/lib/python3.9/site-packages/sipbuild/api.py", line 46, in build_wheel
          project = AbstractProject.bootstrap('wheel',
        File "/tmp/pip-build-env-rtbrazp0/overlay/lib/python3.9/site-packages/sipbuild/abstract_project.py", line 87, in bootstrap
          project.setup(pyproject, tool, tool_description)
        File "/tmp/pip-build-env-rtbrazp0/overlay/lib/python3.9/site-packages/sipbuild/project.py", line 585, in setup
          self.apply_user_defaults(tool)
        File "project.py", line 65, in apply_user_defaults
          super().apply_user_defaults(tool)
        File "/tmp/pip-build-env-rtbrazp0/overlay/lib/python3.9/site-packages/pyqtbuild/project.py", line 70, in apply_user_defaults
          super().apply_user_defaults(tool)
        File "/tmp/pip-build-env-rtbrazp0/overlay/lib/python3.9/site-packages/sipbuild/project.py", line 236, in apply_user_defaults
          self.builder.apply_user_defaults(tool)
        File "/tmp/pip-build-env-rtbrazp0/overlay/lib/python3.9/site-packages/pyqtbuild/builder.py", line 69, in apply_user_defaults
          raise PyProjectOptionException('qmake',
      sipbuild.pyproject.PyProjectOptionException
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.

解决方法 #

方法1：直接安装系统仓库预编译包（推荐） #

Raspbian bullseye仓库提供了预编译的PyQt6包，无需编译，直接执行：

sudo apt update && sudo apt install -y python3-pyqt6

方法2：用pip安装预编译轮子（避免本地编译） #

piwheels提供了树莓派专属的预编译PyQt6轮子，强制使用预编译包：

pip install PyQt6 --only-binary :all:

方法3：安装编译依赖后再尝试pip安装 #

如果必须从源码编译，先安装Qt6开发依赖及适配工具：

# 安装Qt6开发工具和依赖
sudo apt update && sudo apt install -y qt6-base-dev qt6-tools-dev-tools
# 升级sip和pyqtbuild到兼容版本
pip install --upgrade sip pyqtbuild
# 再安装PyQt6
pip install PyQt6

报错原因 #

两次报错最终指向sipbuild.pyproject.PyProjectOptionException，本质原因：

• pip默认尝试从源码编译PyQt6，但本地缺少Qt6的qmake工具及开发库
• 旧版本pip与sip/pyqtbuild版本不兼容，导致元数据生成失败
• 源码编译对树莓派硬件压力大，易出现依赖不匹配问题

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