Ubuntu安装PySide6开发桌面应用实践_Java

一、引言

最近接触了python相关方向的任务，需要开发一个桌面应用对接大模型做测试。于是有了这篇。

二、ubuntu非桌面端安装pyside6

本来嘛，ubuntu桌面系统直接安装pyside6，再装一个vscode就行，无奈手头只有一台windows，暂时先通过 wsl2来模拟跑一下。

2.1、wsl2 ubuntu安装基础工具

首先安装pip：

sudo apt update
sudo apt install python3-pip

之后，通过pip安装 pyside6：

pip3   install pyside6
error: externally-managed-environment

× this environment is externally managed
╰─> to install python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    if you wish to install a non-debian-packaged python package,
    create a virtual environment using python3 -m venv path/to/venv.
    then use path/to/venv/bin/python and path/to/venv/bin/pip. make
    sure you have python3-full installed.

    if you wish to install a non-debian packaged python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. make sure you have pipx installed.

    see /usr/share/doc/python3.12/readme.venv for more information.

note: if you believe this is a mistake, please contact your python installation or os distribution provider. you can override this, at the risk of breaking your python installation or os, by passing --break-system-packages.
hint: see pep 668 for the detailed specification.

原因是ubuntu系统为了保护系统 python 环境，禁止直接用 pip 安装全局包，这是 python pep 668 规范的安全限制。

其实就是推荐你先设个虚拟环境，再安装。

# 1. 创建虚拟环境（指定存放路径，比如 ~/pyside6_venv）
python3 -m venv ~/pyside6_venv
# 2. 激活虚拟环境（每次使用前都需要执行）
source ~/pyside6_venv/bin/activate

创建虚拟环境报错：

python3 -m venv ~/pyside6_venvthe virtual environment was not created successfully because ensurepip is notavailable. on debian/ubuntu systems, you need to install the python3-venvpackage using the following command.

apt install python3.12-venv

you may need to use sudo with that command. after installing the python3-venvpackage, recreate your virtual environment.

failing command: /home/iqos/pyside6_venv/bin/python3

原因是我的ubuntu系统缺少创建 python 虚拟环境必需的 python3.12-venv 包。需要先安装这个。

sudo apt install python3.12-venv  -y

之后再创建并激活虚拟环境即可。

接下来安装 pyside6：

pip install pyside6
collecting pyside6
  downloading pyside6-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl.metadata (5.3 kb)
collecting shiboken6==6.10.2 (from pyside6)
  downloading shiboken6-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl.metadata (2.5 kb)
collecting pyside6_essentials==6.10.2 (from pyside6)
  downloading pyside6_essentials-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl.metadata (3.7 kb)
collecting pyside6_addons==6.10.2 (from pyside6)
  downloading pyside6_addons-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl.metadata (4.0 kb)
downloading pyside6-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl (563 kb)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 563.4/563.4 kb 979.5 kb/s eta 0:00:00
downloading pyside6_addons-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl (170.7 mb)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 170.7/170.7 mb 172.0 kb/s eta 0:00:00
downloading pyside6_essentials-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl (77.0 mb)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 77.0/77.0 mb 136.9 kb/s eta 0:00:00
downloading shiboken6-6.10.2-cp39-abi3-manylinux_2_34_x86_64.whl (273 kb)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 273.1/273.1 kb 26.2 kb/s eta 0:00:00
installing collected packages: shiboken6, pyside6_essentials, pyside6_addons, pyside6
successfully installed pyside6-6.10.2 pyside6_addons-6.10.2 pyside6_essentials-6.10.2 shiboken6-6.10.2

到这一步就安装结束了。接下来是安装windows版的vscode，然后配置wsl来开发。

2.2、windows下安装vscode

2.2.1、第一步：配置 wsl 支持 gui 显示

# 在 wsl 终端执行
wsl --version  # 查看版本，确保有 wslg 相关信息
wsl -l -v      # 检查 ubuntu 发行版的版本是 2

如果版本是 1，执行 wsl --set-version ubuntu 2 切换到 wsl 2（需等待几分钟）。

2.2.2、第二步：安装 wsl 所需的 gui 依赖（ubuntu 端）

即使有 wslg，也需要安装基础的 x11 依赖才能运行 qt 程序：

sudo apt update
sudo apt install -y libx11-6 libxcb1 libxkbcommon-x11-0 libgl1-mesa-glx

这里出现错误：

e: package 'libgl1-mesa-glx' has no installation candidate

libgl1-mesa-glx 是 opengl 渲染依赖，ubuntu 22.04 lts 及以上版本中，这个包已被 libgl1-mesa-dri + libgl1 替代，直接安装会提示找不到，我们换一套兼容所有 ubuntu 桌面版本的依赖安装命令即可。

直接安装通用的依赖即可：

sudo apt update && sudo apt install -y \
    python3-pip \
    python3-venv \
    libx11-6 \
    libxcb1 \
    libxkbcommon-x11-0 \
    libgl1 \
    libgl1-mesa-dri \
    libqt6gui6 \
    libqt6core6 \
    libqt6widgets6

2.2.3、第三步：验证 gui 功能（可选）

安装一个简单的 gui 工具测试：

sudo apt install -y x11-apps
xeyes  # 运行后会在 windows 桌面弹出一个眼睛跟随鼠标的窗口，说明 gui 配置成功

2.2.4、安装windows 端 vscode 连接 wsl 开发

1.安装 windows 版 vscode

从 vscode 官网下载 windows 版并安装（不是 ubuntu 端的 vscode）。

2.安装中文语言包

打开 windows 端 vscode → 扩展面板（ctrl+shift+x）→ 搜索并安装 chinese (simplified) (简体中文) language（微软官方插件）。安装完重启应用中文

3.安装 wsl 插件

打开 windows 端 vscode → 扩展面板（ctrl+shift+x）→ 搜索并安装 remote - wsl（微软官方插件）。

4.连接 wsl 环境

安装完成后，点击 vscode 左下角的「><」图标 → 选择「new wsl window using distro…」→ 选择你的 ubuntu 发行版。
此时会打开一个新的 vscode 窗口，标题栏显示「wsl: ubuntu」，说明已连接到 wsl 环境。

点击左侧的打开文件夹…，或者按快捷键 ctrl+k ctrl+o，在弹出的对话框中选择 wsl 里的项目目录（例如 ~/pyside6_demo）。

如果没有，输入~，回车打开ubuntu内文件夹列表，左侧边栏点击新建项目目录。

然后进入目录下，新建一个main.py，输入示例代码，点击左上方右侧…中的运行，结果提示：

示例代码：

import sys
from pyside6.qtwidgets import qapplication, qmainwindow, qlabel, qpushbutton, qvboxlayout, qwidget

class mainwindow(qmainwindow):
    def __init__(self):
        super().__init__()
        self.setwindowtitle("wsl pyside6 测试")
        self.setfixedsize(400, 200)
        
        central = qwidget()
        self.setcentralwidget(central)
        layout = qvboxlayout(central)
        
        self.label = qlabel("hello wsl + pyside6!")
        layout.addwidget(self.label)
        
        btn = qpushbutton("点击我")
        btn.clicked.connect(lambda: self.label.settext("windows 显示 wsl 窗口！"))
        layout.addwidget(btn)

if __name__ == "__main__":
    app = qapplication(sys.argv)
    win = mainwindow()
    win.show()
    sys.exit(app.exec())