在统信UOS上搭建PyQt5开发环境需三步：先验证并安装Python3及pip3；再用APT安装python3-pyqt5和qttools5-dev-tools（含Designer、pyuic5等）；最后测试designer启动、pyuic5转换UI文件，并处理QT_QPA_PLATFORMTHEME等兼容性问题。
在统信UOS上搭建PyQt5开发环境，需同时满足Python解释器可用、PyQt5库可导入、Qt Designer等配套工具能调用三个基本条件，缺一不可。
确认并准备Python基础环境
统信UOS桌面版通常预装Python 3.9或3.10，但pip3可能未安装，且python3命令未必已设为默认。
打开终端，执行：python3 --version，确认输出类似Python 3.10.12；若报错“command not found”，则需先运行sudo apt install python3。
接着执行：pip3 --version；若提示“command not found”，立即运行sudo apt install python3-pip补全——【缺少pip3会导致后续所有Python包安装失败】。
验证系统是否已提供pyuic5和pyrcc5命令（PyQt5编译UI资源必需）：输入which pyuic5，若无输出，说明Qt工具链尚未就位，需进入下一步。
安装PyQt5核心库与Qt开发工具集
这一步必须同时安装PyQt5运行时库和Qt官方配套工具，否则Designer打不开、UI文件无法转换为Python代码。
方法一：APT一键安装（推荐，兼容性高）
执行命令：sudo apt install -y python3-pyqt5 python3-pyqt5.qtwebengine qttools5-dev-tools。
其中python3-pyqt5.qtwebengine用于支持Web内容嵌入，非必需但建议保留；qttools5-dev-tools包含designer、assistant、linguist等，是图形化开发的关键。
方法二：pip3安装（适用于需要特定版本或虚拟环境隔离）
先创建项目目录并进入：mkdir mypyqt && cd mypyqt；
新建venv：python3 -m venv venv；
激活：source venv/bin/activate；
再执行：pip install PyQt5==5.15.9（指定5.15.9因该版本在UOS V20上通过全功能测试）。
注意：pip安装的PyQt5不附带designer命令，必须额外安装qttools5-dev-tools（APT方式），否则无法调出UI设计器。
验证并调用Qt Designer与pyuic5
第一步：启动Qt Designer
在终端中直接输入designer，回车。若弹出空白设计窗口，说明工具链已就位；若提示“command not found”，请返回上一步重新安装qttools5-dev-tools。
第二步：生成可运行的Python UI文件
用Designer新建一个Widget，保存为main.ui；
在该文件所在目录下执行：pyuic5 main.ui -o ui_main.py；
成功后将生成ui_main.py，可用python3 ui_main.py测试是否能显示界面——若报错ModuleNotFoundError: No module named 'PyQt5'，说明当前Python环境未识别到PyQt5，需检查是否在venv中未激活，或APT安装路径未被pip环境索引。
第三步：配置PyCharm或VS Code外部工具（可选但实用）
以PyCharm为例：打开Settings → Tools → External Tools，点击+号添加新工具；
名称填PyUIC5，程序填/usr/bin/pyuic5，参数填$FileName$ -o $FileNameWithoutExtension$_ui.py，工作目录填$FileDir$；
配置完成后，右键.ui文件即可一键生成_ui.py。
解决常见运行时错误
错误现象：“QApplication: invalid style override passed, ignoring it”或界面字体异常
原因：UOS默认使用ukui主题，与Qt原生样式冲突。
临时修复：在Python脚本开头插入以下两行：
import osos.environ["QT_QPA_PLATFORMTHEME"] = "kvantum"
若系统未安装Kvantum主题，先执行：sudo apt install kvantum，再在Kvantum Manager中启用任一Qt风格。
错误现象：运行含QWebEngineView的程序崩溃
原因：Qt WebEngine依赖OpenGL上下文，UOS部分显卡驱动未启用GLX。
强制启用：export QT_WEBENGINE_DISABLE_SANDBOX=1，然后运行程序；长期使用建议升级Mesa驱动：sudo apt install mesa-utils libgl1-mesa-dri。
