我们将使用 PyQt6 作为示例，因为它是最现代、功能最全的 Qt Python 绑定。PyQt5 的安装过程也几乎完全相同。

目录

1. 环境准备
2. 安装 Python
3. 安装 Qt
4. 安装 PyQt6
5. 验证安装
6. 创建并运行你的第一个 Qt 应用
7. 高级主题：虚拟环境
8. 常见问题与解决方案

环境准备

在开始之前,请确保你的 Linux 系统是最新的，并且安装了基本的编译工具。

打开终端,运行以下命令：

# 对于 Debian/Ubuntu 系统
sudo apt update
sudo apt upgrade -y
sudo apt install -y build-essential
# 对于 Fedora/CentOS/RHEL 系统
sudo dnf update -y
sudo dnf groupinstall "Development Tools" -y

build-essential (Debian/Ubuntu) 或 "Development Tools" (Fedora) 包含了编译 C/C++ 代码所需的 gcc, g++, make 等工具，这在编译 PyQt 的某些模块时是必需的。

安装 Python

大多数现代 Linux 发行版（如 Ubuntu 20.04+, Fedora 28+）都预装了 Python 3，我们可以直接使用它。

检查 Python 版本

在终端输入：

python3 --version

你应该会看到类似 Python 3.8.10 或更高版本的输出。强烈建议使用 Python 3.6 或更高版本。

如果需要安装或升级 Python

如果你的系统版本过旧,或者你想安装一个更新的 Python 版本（例如通过 pyenv），可以参考以下方法：

使用包管理器（简单，但版本可能不是最新的）

# 对于 Debian/Ubuntu
sudo apt install python3 python3-pip
# 对于 Fedora
sudo dnf install python3 python3-pip

使用 pyenv（推荐，可以轻松管理多个 Python 版本）

pyenv 是一个强大的 Python 版本管理工具。

1. 安装依赖:

   # Ubuntu/Debian
   sudo apt update
   sudo apt install -y make build-essential libssl-dev zlib1g-dev \
   libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
   libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
   # Fedora
   sudo dnf install -y git make gcc zlib-devel bzip2-devel \
   readline-devel sqlite-devel openssl-devel tk-devel libffi-devel xz-devel

2. 安装 pyenv:

   curl https://pyenv.run | bash

3. 配置环境变量: 将以下内容添加到你的 shell 配置文件中（~/.bashrc 或 ~/.zshrc）：

   export PYENV_ROOT="$HOME/.pyenv"
   command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
   eval "$(pyenv init -)"

   然后重新加载配置文件：

   exec "$SHELL"

4. 安装 Python:

   # 安装最新的稳定版 Python (3.11.4)
   pyenv install 3.11.4
   # 设置全局默认 Python 版本
   pyenv global 3.11.4

安装 Qt

Qt 本身是一个 C++ 框架，所以我们需要安装它的库、开发工具和 Qt Creator（可选的 IDE）。

安装 Qt 库和开发工具

对于 Debian/Ubuntu 系统:

# 安装 Qt6 核心库和开发工具
sudo apt install qt6-base-dev qt6-declarative-dev
# 如果需要其他模块，例如用于绘图的 qt6-svg-dev
sudo apt install qt6-svg-dev

对于 Fedora/CentOS/RHEL 系统:

# 安装 Qt6 核心库和开发工具
sudo dnf install qt6-qtbase-devel qt6-qtdeclarative-devel
# 如果需要其他模块
sudo dnf install qt6-qtsvg-devel

安装 Qt Creator (可选但推荐)

Qt Creator 是一个功能强大的跨平台 IDE，专门为 Qt 开发优化。

对于 Debian/Ubuntu 系统:

sudo apt install qtcreator

对于 Fedora/CentOS/RHEL 系统:

sudo dnf install qt-creator

安装后,你可以在应用程序菜单中找到并启动 Qt Creator。

安装 PyQt6

Python 和 Qt 环境都已就绪，我们可以安装 Python 的 Qt 绑定库了。pip 是 Python 的包管理器。

# 强烈建议使用 pip3
python3 -m pip install --upgrade pip
python3 -m pip install PyQt6

如果你需要使用 Qt 的数据可视化模块（如 QCharts, QML 等），可以安装相应的扩展包：

python3 -m pip install PyQt6-Qt6 PyQt6-Charts PyQt6-WebEngine

重要提示：

• 不要使用 sudo pip install，这可能会导致系统 Python 环境的混乱，我们将在下一节介绍如何使用虚拟环境来避免这个问题。
• pip 会自动下载并编译 PyQt6，这可能需要几分钟时间。

验证安装

为了确保一切正常,让我们进行一个简单的验证。

1. 检查 pip 是否能找到 PyQt6:

   pip3 show PyQt6

   如果安装成功,它会显示 PyQt6 的版本、位置等信息。

2. 使用 qtpy 进行兼容性检查 (推荐): qtpy 是一个兼容层，可以让你用 import PyQt5 或 import PyQt6 的方式无缝切换底层绑定，这是一个很好的编程习惯。

   pip3 install qtpy
   python3 -c "from PyQt6.QtCore import QVersionNumber; print('PyQt6 and Qt are working!')"

   如果没有报错,并打印出提示信息，说明你的环境已经完全配置好了。

创建并运行你的第一个 Qt 应用

让我们创建一个简单的窗口来测试环境。

1. 创建一个 Python 文件: 使用你喜欢的文本编辑器（如 vim, nano 或 VS Code）创建一个名为 hello_qt.py 的文件。

   nano hello_qt.py

2. 粘贴以下代码:

   import sys
   from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
   # 1. 创建一个 QApplication 实例
   # 每一个 PyQt 应用都必须有一个 QApplication 实例
   app = QApplication(sys.argv)
   # 2. 创建一个窗口部件
   window = QWidget()
   window.setWindowTitle('My First PyQt App')
   window.setGeometry(300, 300, 350, 200) # x, y, width, height
   # 3. 创建一些控件
   hello_msg = QLabel('<h1>Hello, World!</h1>', parent=window)
   layout = QVBoxLayout()
   layout.addWidget(hello_msg)
   window.setLayout(layout)
   # 4. 显示窗口
   window.show()
   # 5. 运行应用的主循环
   # sys.exit() 确保程序可以干净地退出
   sys.exit(app.exec())

3. 运行应用: 在终端中，进入文件所在目录，然后运行：

   python3 hello_qt.py

   如果一切顺利,你应该会看到一个标题为 "My First PyQt App" 的窗口，里面显示着 "Hello, World!"。

高级主题：虚拟环境

为了避免不同项目之间的依赖冲突,并保持系统环境的清洁，强烈建议为每个项目创建一个独立的虚拟环境。

1. 安装 venv 模块: venv 是 Python 3 自带的虚拟环境工具。

   # 对于 Debian/Ubuntu，可能需要单独安装
   sudo apt install python3-venv

2. 为项目创建虚拟环境: 假设你的项目文件夹是 my_qt_project：

   mkdir my_qt_project
   cd my_qt_project
   python3 -m venv venv

   这会在 my_qt_project 目录下创建一个名为 venv 的文件夹，里面包含了独立的 Python 解释器和 pip。

3. 激活虚拟环境:

   source venv/bin/activate

   激活后,你的终端提示符前面会出现 (venv)，表示你正在虚拟环境中工作。

4. 在虚拟环境中安装依赖: 现在所有的 pip 安装都只会影响这个虚拟环境。

   (venv) pip install PyQt6

5. 退出虚拟环境: 当你完成工作后，只需输入：

   deactivate

常见问题与解决方案

1. Q: 运行 pip install PyQt6 时出现 fatal error: Python.h: No such file or directory 错误。 A: 这意味着你的系统缺少 Python 的开发头文件，请返回 第 1 步，确保你已经安装了 python3-dev (Debian/Ubuntu) 或 python3-devel (Fedora) 包。

   # Debian/Ubuntu
   sudo apt install python3-dev
   # Fedora
   sudo dnf install python3-devel

2. Q: Qt Creator 无法找到 Python 或 PyQt。 A: 你需要在 Qt Creator 中手动配置 Python 解释器。

   1. 打开 Qt Creator，进入 Tools -> Options。
   2. 在左侧导航栏中找到 Kits。
   3. 选择你的 Desktop 套件。
   4. 在右侧的 CMake 或 QMake 选项卡中，确保 Python 解释器路径指向你虚拟环境中的 python (/home/user/my_qt_project/venv/bin/python)。
   5. 你可能还需要在 Build & Run -> PySide (或 PyQt) 中指定 pyrcc 和 pyuic 工具的路径。

3. Q: 我想用 PyQt5 而不是 PyQt6。 A: 安装过程非常相似，只需将 PyQt6 替换为 PyQt5 即可。

   pip3 install PyQt5

   并将代码中的 import PyQt6 改为 import PyQt5，大部分 API 在两个版本中都是兼容的。

4. Q: pip 安装速度很慢。 A: 你可以配置使用国内镜像源来加速下载。 创建或编辑 ~/.pip/pip.conf 文件 (如果目录不存在，请先创建)：

   [global]
   index-url = https://pypi.tuna.tsinghua.edu.cn/simple

   这将使用清华大学的镜像源,速度会快很多。

希望这份详细的指南能帮助你在 Linux 上顺利搭建起 Python + Qt 的开发环境！