Ubuntu20.04下Python虚拟环境安装PyQt5失败的求助及版本疑问

问题背景 #

• 系统：Ubuntu 20.04
• 场景：Python虚拟环境内使用pip安装PyQt5 5.15.8及以上版本均失败，仅5.15.5版本可成功安装
• 干扰因素：系统存在3个不同版本的pip；通过apt可在系统site-packages目录成功安装PyQt5，但该方式不适用于虚拟环境
• 核心报错日志：

ERROR: Command errored out with exit status 1:
 command: /home/ntolb/CODING_PROJECTS/python_workspaces/webscraping-projects_workspaces/scr-proj_ws1/bin/python /tmp/tmpuo_qeg4k prepare_metadata_for_build_wheel /tmp/tmpo5bkbzi5
   cwd: /tmp/pip-install-9g1_3u0b/pyqt5
 complete output (36 lines):
 Querying qmake about your Qt installation...
 Traceback (most recent call last):
   File "/tmp/tmpuo_qeg4k", 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/tmpuo_qeg4k", line 280, in <module>
        main()
      File "/tmp/tmpuo_qeg4k", line 263, in main
        json_out['return_val'] = hook(**hook_input['kwargs'])
      File "/tmp/tmpuo_qeg4k", line 130, in prepare_metadata_for_build_wheel
        return _get_wheel_metadata_from_wheel(backend, metadata_directory,
      File "/tmp/tmpuo_qeg4k", line 159, in _get_wheel_metadata_from_wheel
        whl_basename = backend.build_wheel(metadata_directory, config_settings)
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/sipbuild/api.py", line 28, in build_wheel
        project = AbstractProject.bootstrap('wheel',
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/sipbuild/abstract_project.py", line 74, in bootstrap
        project.setup(pyproject, tool, tool_description)
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/sipbuild/project.py", line 608, in setup
        self.apply_user_defaults(tool)
      File "/tmp/pip-install-9g1_3u0b/pyqt5/project.py", line 68, in apply_user_defaults
        super().apply_user_defaults(tool)
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/pyqtbuild/project.py", line 51, in apply_user_defaults
        super().apply_user_defaults(tool)
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/sipbuild/project.py", line 237, in apply_user_defaults
        self.builder.apply_user_defaults(tool)
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/pyqtbuild/builder.py", line 58, in apply_user_defaults
        self._get_qt_configuration()
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/pyqtbuild/builder.py", line 483, in _get_qt_configuration
        for line in project.read_command_pipe([self.qmake, '-query']):
      File "/tmp/pip-build-env-gbcn5_fc/overlay/lib/python3.8/site-packages/sipbuild/project.py", line 575, in read_command_pipe
        raise UserException(
    sipbuild.exceptions.UserException
    ----------------------------------------
ERROR: Command errored out with exit status 1: /home/ntolb/CODING_PROJECTS/python_workspaces/webscraping-projects_workspaces/scr-proj_ws1/bin/python /tmp/tmpuo_qeg4k prepare_metadata_for_build_wheel /tmp/tmpo5bkbzi5 Check the logs for full command output.

报错原因分析 #

1. sipbuild版本不兼容：新版PyQt5依赖的sipbuild库需要包含prepare_metadata_for_build_wheel方法，旧版本的sipbuild缺少该属性，触发第一个AttributeError。
2. 虚拟环境无法访问系统Qt配置：apt安装的Qt库位于系统路径，虚拟环境默认隔离系统依赖，导致编译PyQt5时无法找到qmake工具，执行qmake -query失败抛出UserException。
3. 多pip版本干扰：系统中存在多个pip版本，若操作时未明确使用虚拟环境内的pip，可能导致依赖安装混乱，加剧版本不兼容问题。
4. PyQt5版本差异：5.15.5版本的编译逻辑对Qt路径的依赖更宽松，或当时的依赖版本兼容性更好，因此能绕过上述问题完成安装。

解决方案 #

步骤1：确保使用虚拟环境内的pip并升级核心依赖 #

先激活目标虚拟环境：

source /home/ntolb/CODING_PROJECTS/python_workspaces/webscraping-projects_workspaces/scr-proj_ws1/bin/activate

升级pip及PyQt5编译所需的依赖：

pip install --upgrade pip setuptools wheel sip pyqtbuild

步骤2：指定系统qmake路径给虚拟环境 #

Ubuntu 20.04通过apt安装的Qt5，qmake通常位于/usr/lib/x86_64-linux-gnu/qt5/bin/qmake，可通过which qmake-qt5命令确认路径。

方式一：安装时直接指定qmake路径

pip install PyQt5 --config-settings --qmake=/usr/lib/x86_64-linux-gnu/qt5/bin/qmake

方式二：先设置环境变量再安装

export QMAKE=/usr/lib/x86_64-linux-gnu/qt5/bin/qmake
pip install PyQt5

步骤3：尝试安装预编译wheel包 #

若上述方法仍失败，可强制使用PyPI上的预编译wheel包，避免本地编译：

pip install PyQt5 --only-binary=PyQt5

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