首页 > 脚本专栏 > python > Ubuntu安装PySide6开发桌面应用

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

2026-04-23 10:08:46 作者：Pisces_224

文章介绍了在Ubuntu非桌面端安装PySide6并使用WSL2在Windows上开发Python桌面应用的全过程,首先,通过wS安装基础工具并用使用pip安装PySide6,接着,在WindowsD安装VSCode并配置WSL支持支持GUI显示,最后D在WSL中开发Python桌面应用

一、引言

最近接触了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())