PySide6部署工具：Python版Qt的部署工具#

pyside6-deploy 是一个简单易用的工具，可以将 PySide6 应用程序部署到不同的平台上。它是围绕 Python 编译器 Nuitka 的封装，该编译器将您的 Python 代码编译为 C 代码，并与 libpython 链接以生成最终的执行文件。

生成的最终执行文件在 Windows 上具有 .exe 后缀，在 Linux 上具有 .bin 后缀，在 macOS 上具有 .app 后缀。

注意

尽管建议为 pyside6-deploy 使用 Python 虚拟环境，但不要将虚拟环境添加到您要部署的应用程序目录中。 pyside6-deploy 将尝试对该 venv 文件夹进行打包，并最终失败。

如何使用？#

您可以使用两种不同的方法使用 pyside6-deploy 将 PySide6 应用程序进行部署

方法 1：使用主 Python 入口点文件#

在这种方法中，您将 pyside6-deploy 指向包含项目主 Python 入口点文件（即包含 if __name__ == "__main__": 的文件）的文件。命令看起来像这样

pyside6-deploy /path/to/main_file.py

运行命令后，pyside6-deploy 将安装部署所需的所有依赖项到 Python 环境中。

如果您的主 Python 入口点文件名为 main.py，则无需指向文件名。您可以在没有任何选项的情况下运行 pyside6-deploy，它将正常工作。

注意

如果您的项目包含一个 pysidedeploy.spec 文件，该文件是在项目目录下首次运行 pyside6-deploy 时生成的，那么在随后的 pyside6-deploy 运行过程中，您可以在不指定主 Python 入口点文件的情况下直接运行 pyside6-deploy。它会从 pysidedeploy.spec 文件中获取主文件路径。要了解更多关于由 pysidedeploy.spec 文件控制的部署参数，请阅读 pysidedeploy。

方法2：使用pyhsidedeploy.spec配置文件

当您首次运行 pyside6-deploy 时，它会创建一个名为 pysidedeploy.spec 的文件，并将其存储在项目目录下。该文件控制影响部署过程的各项参数。在项目目录上对 pyside6-deploy 的任何后续运行，都不需要主 Python 入口点文件等额外参数。您还可以指定 pyside6-deploy 的 pysidedeploy.spec 文件路径（如果它不在同一目录中），以从该文件中获取参数。可以使用以下命令完成此操作：

pyside6-deploy -c /path/to/pysidedeploy.spec

pyhsidedeploy.spec

如上所述，在方法2中，您可以使用该文件来控制部署过程的各项参数。该文件包含多个部分，每个部分包含多个键（参数）及其分配的值。此类文件的优点有两点：

使用命令行，您可以在不每次都指定参数的情况下控制部署参数。它被永久保存到文件中，并且后续任何时间较晚的运行都会让用户了解其上一次部署的参数。
由于这些参数被保存到文件中，因此它们可以纳入版本控制。这使用户能够更好地控制部署过程。例如，当您决定排除更多 QML 插件时，或者想要将更多 Nuitka 选项包含到可执行文件中。

该文件也用作 pyside6-android-deploy 工具的配置文件。这里的优势在于，您可以使用一个单独的文件来控制对不同平台的部署。

与 pyside6-deploy 相关的参数如下：

app

title：应用程序的名称
project_dir：项目目录。一般假设项目目录是主 Python 入口点文件的父目录
input_file：主 Python 入口点文件的路径
project_file：如果存在，则指向 Qt Creator Python 项目文件.pyproject 文件的路径。此类文件确保部署过程在捆绑可执行文件时不会考虑不必要的文件。
exec_directory：最终可执行文件生成的目录。
icon：应用程序使用的图标。对于Windows，图标图像应该是.ico格式，对于macOS，应该是.icns格式，Linux则接受所有标准图像格式。

python

python_path：Python可执行文件的路径。建议在虚拟环境中运行部署过程，因为某些Python包将被安装到Python环境中。
packages：为了使部署工作，安装到Python环境中的Python包。默认情况下，会安装Python包nuitka、ordered_set和zstandard。如果部署平台是基于Linux的，那么也会安装patchelf。

qt

qml_files：以逗号分隔的路径，指向所有与可执行文件捆绑的QML文件
excluded_qml_plugins：使用Nuitka进行QML部署的问题在于，所有的QML插件也将与其可执行文件捆绑在一起。当捆绑插件时，插件的Qt模块的二进制文件也将被封装进去。例如，像QtWebEngine这样的体积较大的模块也会添加到您的可执行文件中，即使您在代码中没有使用它。您可以使用excluded_qml_plugins参数明确指定哪些QML插件被排除。当存在以下Qt模块时，pyside6-deploy会自动检查QML文件，并排除相应的Qt模块，如果它们不存在：
```
QtQuick, QtQuick3D, QtCharts, QtWebEngine, QtTest, QtSensors
```
仅检查上述6个Qt模块的存在，是因为它们在所有Qt模块中具有最大的体积二进制文件。通过这种方式，您可以大大减少可执行文件的大小。
modules：以逗号分隔的应用程序使用的所有Qt模块列表。与pysidedeploy.spec中的其他配置选项一样，此选项也由pyside6-deploy自动计算。但是，如果用户想明确包含某些Qt模块，可以将模块名称添加到此列表中，无需使用Qt前缀。例如使用Network而不是QtNetwork。
plugins：以逗号分隔的应用程序使用的所有Qt插件列表。与pysidedeploy.spec中的其他配置选项一样，此选项也由pyside6-deploy自动计算。但是，如果用户想明确包含某些Qt插件，可以将插件名称添加到此列表中。要查看与PySide6捆绑的所有插件，请查看Python安装中PySide6的site-packages目录下的plugins文件夹。插件名称对应于文件夹名称。

nuitka

macos.permissions：仅适用于macOS。此选项列表了macOS应用程序使用的权限，这些权限可以通过macOS应用程序包的Info.plist文件中所谓的UsageDescription字符串找到。通常，pyside6-deploy会自动找到这些权限。然而，用户还可以使用格式<UsageDescriptionKey>:<Short Description>明确指定它们。例如，相机权限指定为：
```
NSCameraUsageDescription:CameraAccess
```
extra_args：指定的任何额外Nuitka参数。它指定为空格分隔的命令行参数，就像您使用命令行通过Nuitka一样指定它。默认情况下，它包含以下参数
```
--quiet --noinclude-qt-translations=True
```

命令行选项#

最重要的命令行选项是主Python入口点文件和pysidedeploy.spec文件。如果没有这些文件或它们提供了命令行选项，则pyside6-deploy假设您的当前工作目录不包含PySide6项目。

以下是pyside6-deploy的所有命令行选项

主入口点文件：此选项没有名称或标志，也不受其限制。这使得pyside6-deploy可以像这样使用
```
pyside6-deploy /path/to/main_file.py
```
-c/–config-file：此选项用于显式指定pysidedeploy.spec的路径
–init：用于仅创建pysidedeploy.spec文件。用法
```
pyside6-deploy /path/to/main --init
```
-v/–verbose：在详细模式下运行pyside6-deploy。
–dry-run：显示将要运行的最终Nuitka命令。
–keep-deployment-files：当添加此选项时，它会保留由Nuitka在部署过程中创建的构建文件夹。
Nuitka在部署过程中创建的
-f/–force：使用此选项时，它会强制通过所有输入提示。如果尚未在虚拟环境中，pyside6-deploy将提示用户创建Python虚拟环境。使用此选项，无论当前Python环境是否为虚拟环境，都将使用当前Python环境。
–name：应用程序名称。
–extra-ignore-dirs：项目目录内的以逗号分隔的目录名称。这些目录将在搜索与项目相关的Python文件时被跳过。
–extra-modules：要添加到应用程序的Qt模块的逗号分隔列表，如果它们未自动找到。模块名称可以不包含Qt前缀指定，也可以包含它，例如：Network和QtNetwork都有效。

注意事项#

为了通过仅捆绑必要的插件来有效地工作，以下实用工具需要安装到系统中

操作系统	依赖项	安装
Windows	dumpbin	与MSVC一同提供。通过运行vcvarsall.bat将其添加到PATH
Linux	readelf	默认情况下可用的
macOS	dyld_info	macOS 12及更高版本默认可用