Python 运维（四）：使用 PyInstaller 将 Python 程序打包成可执行文件

大家好，我是水滴~~

PyInstaller是一款强大的Python打包工具，通过将Python程序转换成可执行文件，它简化了程序的分享和分发过程。本文从简介、安装、使用以及典型案例四个方面对PyInstaller进行了介绍。

文章内容包含大量的示例代码，希望能够帮助新手同学快速入门。

《Python入门核心技术》专栏总目录?点这里

---

一、简介

PyInstaller 是一个用于将 Python 程序打包成可执行文件的工具。它可以将你的 Python 脚本、模块和依赖项打包为独立的应用程序，使其可以在没有安装 Python 解释器的环境中运行。
PyInstaller 的主要目标是创建一个独立的、可执行的应用程序，无需用户担心 Python 环境、依赖项和配置。它将 Python 脚本和依赖项捆绑在一起，以创建一个单个的可执行文件或一个文件夹，其中包含应用程序所需的所有文件。
PyInstaller 支持多个操作系统，包括 Windows、Mac 和 Linux，并且可以打包为针对特定平台的可执行文件。它可以处理包括 GUI 应用程序、命令行工具和其他类型的 Python 脚本在内的各种类型的程序。
使用 PyInstaller，你可以轻松地分发和部署你的 Python 应用程序，无需用户事先安装 Python 环境和相关依赖项。这使得将 Python 程序转换为独立应用程序变得更加方便，特别是在与非技术用户共享和交付软件时。
PyInstaller 提供了一些选项和配置，允许你自定义打包行为，例如指定生成的可执行文件的名称、图标、打包模式和其他设置。它还提供了一些高级功能，如处理资源文件、动态导入和自定义引导过程等。

下面是 PyInstaller 的官方地址：

地址	链接
PyPI	https://pypi.org/project/pyinstaller/
官方文档	https://pyinstaller.org/
GitHub	https://github.com/pyinstaller/pyinstaller

二、安装 PyInstaller

安装 PyInstaller 最新版本：

pip install pyinstaller

升级 PyInstaller 到最新版本：

pip install --upgrade pyinstaller

验证安装：

pyinstaller --version

如果成功安装，将显示 PyInstaller 的版本号。

三、使用 PyInstaller

3.1 基本语法

PyInstaller 的语法相对简单，主要是通过命令行来操作。以下是 PyInstaller 的基本语法简介：

pyinstaller [options] script.py

其中 options 是该命令的选项，script.py 是你要打包的 Python 脚本文件。

下面是一个简单的示例，可以将一个指定的 Python 脚本打包成可执行文件：

pyinstaller myscript.py

执行该命令后，会生成一些文件和目录，如下：

• myscript.spec 文件是 PyInstaller 的配置文件，用于指定打包的详细设置和选项。通常，你可以使用 PyInstaller 命令行工具生成该配置文件，然后对其进行自定义配置。
• build 目录是一个临时目录，用于存储打包过程中生成的临时文件和构建相关的中间文件。这些文件包括生成的 Python 字节码文件、打包后的可执行文件、依赖项文件、资源文件等。
• dist 目录是打包完成后的输出目录，其中包含最终生成的可执行文件和相关的依赖项。该目录中的 myscript.exe 就是最终生成的可执行文件。

3.2 常用选项

PyInstaller 的选项众多，下面根据不同的用途进行的一个分类，选项列表如下：

3.2.1 位置参数

选项	含义
scriptname	要处理的脚本文件的名称，或确切的一个 .spec 文件。如果指定了 .spec 文件，则大多数选项都是不必要的，将被忽略。

3.2.2 选项

选项	含义
-h, --help	显示帮助信息并退出
-v, --version	显示版本信息并退出
--distpath DIR	用于指定输出目录的路径（默认：./dist）。输出目录（也称为分发目录）是 PyInstaller 在打包完成后存放最终生成的可执行文件和相关文件的目录。
--workpath WORKPATH	用于指定工作目录的路径（默认：./build）。工作目录是 PyInstaller 在打包过程中使用的临时目录，用于存储临时文件和构建相关的中间文件。
-y, --noconfirm	在执行打包过程中不需要用户确认任何提示信息，而是自动选择默认选项进行处理。这个选项通常用于批量或自动化打包的情况下，以避免在确认提示阶段需要手动输入确认信息。通过使用 -y 或 --noconfirm 选项，PyInstaller 将自动处理打包过程中的确认提示，节省了用户的交互操作。
--upx-dir UPX_DIR	指定 UPX（可执行文件压缩工具）的目录路径。UPX 是一个流行的可执行文件压缩工具，可以减小生成的可执行文件的大小。PyInstaller 提供了 --upx-dir 选项，让你可以指定 UPX 工具的目录路径，以便 PyInstaller 在打包过程中自动使用 UPX 进行可执行文件的压缩。
--clean	用于在构建之前清理 PyInstaller 缓存并删除临时文件。
--log-level LEVEL	用于设置日志输出的级别。LEVEL 可以是 TRACE、DEBUG、INFO、WARN、DEPRECATION、ERROR、FATAL 之一（默认值：INFO）。也可通过 PYI_LOG_LEVEL 环境变量进行设置。

3.2.3 生成什么

选项	含义
-D, --onedir	默认选项，表示将生成的可执行文件和相关文件组织在一个单独的目录中，而不是单个独立的可执行文件。在此模式下，生成的可执行文件将作为入口点，而其他所需的文件（例如库、资源文件等）将存储在同一目录中。
-F, --onefile	表示将生成的可执行文件及其依赖项打包成一个独立的单个文件。在此模式下，所有的代码、库和资源将捆绑在一个可执行文件中，使得分发和部署更加方便。
--specpath DIR	用于指定生成的 .spec 文件的输出路径。.spec 文件是 PyInstaller 的配置文件，它包含了打包应用程序所需的各种设置和选项。默认情况下，.spec 文件将在当前工作目录中生成。
-n NAME, --name NAME	用于指定生成的可执行文件的名称。（默认值：第一个脚本的基本名称）

3.2.4 绑定什么，在哪里搜索

选项	含义
--add-data SOURCE:DEST	用于将特定的文件或目录添加到生成的可执行文件中。其中 SOURCE 是要添加的源文件或目录的路径，DEST 是在可执行文件中的目标路径。
--add-binary SOURCE:DEST	用于将特定的二进制文件添加到生成的可执行文件中。其中 SOURCE 是要添加的源二进制文件的路径，DEST 是在可执行文件中的目标路径。
-p DIR, --paths DIR	用于指定额外的模块搜索路径。选项允许你添加一个或多个目录，这些目录将被 PyInstaller 用于搜索模块和依赖项。这对于处理特定的模块或库文件位置非常有用，以确保 PyInstaller 能够正确地找到所需的模块。
--hidden-import MODULENAME, --hiddenimport MODULENAME	用于指定需要隐式导入的模块。其中 MODULENAME 是需要隐式导入的模块的名称。
--collect-submodules MODULENAME	用于收集指定模块及其所有子模块并将其打包到生成的可执行文件中。其中 MODULENAME 是要收集子模块的模块的名称。
--collect-data MODULENAME, --collect-datas MODULENAME	用于收集指定模块的数据文件并将其打包到生成的可执行文件中。其中 MODULENAME 是要收集数据文件的模块的名称。
--collect-binaries MODULENAME	用于收集指定模块的二进制文件并将其打包到生成的可执行文件中。其中 MODULENAME 是要收集二进制文件的模块的名称。
--collect-all MODULENAME	用于收集指定模块的所有依赖文件（包括数据文件和二进制文件）并将它们打包到生成的可执行文件中。其中 MODULENAME 是要收集所有依赖文件的模块的名称。
--copy-metadata PACKAGENAME	用于复制指定包的元数据到生成的可执行文件中。其中 PACKAGENAME 是要复制元数据的包的名称。
--recursive-copy-metadata PACKAGENAME	用于递归地复制指定包及其所有依赖包的元数据到生成的可执行文件中。其中 PACKAGENAME 是要递归复制元数据的包的名称。
--additional-hooks-dir HOOKSPATH	用于指定额外的钩子目录，以便在构建过程中加载自定义的钩子脚本。其中 HOOKSPATH 是包含自定义钩子脚本的目录路径。
--runtime-hook RUNTIME_HOOKS	用于指定运行时钩子脚本，以在运行时修改或扩展生成的可执行文件的行为。其中 RUNTIME_HOOKS 是运行时钩子脚本文件的路径。
--exclude-module EXCLUDES	用于在打包过程中排除指定的模块。其中 EXCLUDES 是要排除的模块的名称或模式。
--splash IMAGE_FILE	用于指定启动屏幕图像文件。其中 IMAGE_FILE 是用作启动屏幕的图像文件的路径。

3.2.5 如何生成

选项	含义
-d {all,imports,bootloader,noarchive}, --debug {all,imports,bootloader,noarchive}	用于指定调试模式和调试级别。all：启用所有调试信息；imports：仅显示导入模块的调试信息；bootloader：仅显示启动加载器的调试信息；noarchive：不生成归档文件。
--python-option PYTHON_OPTION	用于传递特定的 Python 解释器选项。其中 PYTHON_OPTION 是要传递给 Python 解释器的选项或参数。
-s, --strip	用于在打包过程中剥离（strip）生成的可执行文件的调试符号信息。
--noupx	用于在打包过程中禁用 UPX 压缩。
--upx-exclude FILE	用于在 UPX 压缩过程中排除指定的文件。其中 FILE 是要在 UPX 压缩过程中排除的文件的路径。

3.2.6 Windows 和 Mac OS X 特定选项

选项	含义
-c, --console, --nowindowed	默认选项，用于生成带有控制台窗口的命令行应用程序。
-w, --windowed, --noconsole	用于生成没有控制台窗口的 GUI 应用程序。
--hide-console {minimize-late,hide-late,hide-early,minimize-early}	用于控制可执行文件是否显示控制台窗口。minimize-late: 在可执行文件启动后最小化控制台窗口；hide-late: 在可执行文件启动后隐藏控制台窗口；hide-early: 在可执行文件启动前隐藏控制台窗口；minimize-early: 在可执行文件启动前最小化控制台窗口。
-i <FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE">, --icon <FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE">	用于指定应用程序的图标文件。<FILE.ico or FILE.exe,ID>：指定一个 ICO 或 EXE 文件作为图标。可以提供一个 ICO 文件的路径或一个 EXE 文件的路径和图标的索引。例如，myicon.ico 或 myapp.exe,0；<FILE.icns>：指定一个 ICNS 文件（适用于 macOS）作为图标。例如，myicon.icns；Image：指定一个图像文件作为图标。可以是各种图像格式，如 PNG、JPEG 等。例如，myimage.png；“NONE”：表示不使用任何图标，生成的可执行文件将使用默认的图标。
--disable-windowed-traceback	用于在生成的可执行文件中禁用窗口化的回溯跟踪信息。默认情况下，当在生成的应用程序中发生错误时，PyInstaller 会显示一个窗口化的回溯跟踪信息，其中包含了有关错误的详细信息。

3.2.7 Windows 特定选项

选项	含义
--version-file FILE	于指定一个版本文件，以在生成的可执行文件中包含版本信息。
-m <FILE or XML>, --manifest <FILE or XML>	用于指定一个应用程序清单文件或 XML 文件。
-r RESOURCE, --resource RESOURCE	用于将资源文件包含在生成的可执行文件中。
--uac-admin	用于在生成的可执行文件中请求管理员权限（UAC）。默认情况下，生成的可执行文件不会请求管理员权限，即使用户拥有管理员权限也不会自动以管理员身份运行。然而，使用 --uac-admin 选项可以使生成的可执行文件在运行时请求管理员权限。
--uac-uiaccess	用于在生成的可执行文件中请求 UIAccess 权限。UIAccess 是一种 Windows 用户权限，允许应用程序在用户界面上与其他应用程序进行交互，即使在安全桌面模式下也可以。通常，请求 UIAccess 权限是为了在用户交互时能够更好地与操作系统进行集成。

3.3 在 Python 代码中运行 PyInstaller

如果你想要在Python代码中运行PyInstaller，你可以使用PyInstaller.__main__中定义的run函数。

例如，下面的代码：

import PyInstaller.__main__

PyInstaller.__main__.run([
    'my_script.py',
    '--onefile',
    '--windowed'
])

等同于以下命令：

pyinstaller my_script.py --onefile --windowed

四、典型案例

PyInstaller是一个常用的Python打包工具，可以将Python代码打包成可执行文件（exe）或可执行的独立应用程序。以下是一些PyInstaller的典型应用案例以及相应的命令示例：

4.1 打包成单个exe文件

pyinstaller --onefile myscript.py

这将生成一个单个的可执行文件 myscript.exe，包含了 myscript.py 的功能。

4.2 打包包含图标的应用程序

pyinstaller --onefile --icon=myicon.ico myscript.py

这将生成一个单个的可执行文件 myscript.exe，并使用指定的图标文件 myicon.ico。

4.3 打包带有GUI界面的应用程序

pyinstaller --onefile --windowed myscript.py

这将生成一个单个的可执行文件 myscript.exe，并在没有控制台窗口的情况下运行应用程序。

4.4 打包带有数据文件的应用程序

pyinstaller --onefile --add-data "data.txt;." myscript.py

这将生成一个单个的可执行文件 myscript.exe，并将 data.txt 文件作为数据文件打包到应用程序中。

4.5 打包带有依赖库的应用程序

pyinstaller --onefile --hidden-import=module myscript.py

这将生成一个单个的可执行文件 myscript.exe，并将指定的依赖库 module 打包到应用程序中。

总结

PyInstaller是一个强大而实用的Python打包工具，能够将Python程序打包成可执行文件，让你的应用程序更易于分享和分发。通过遵循简单的安装和使用步骤，你可以方便地将Python程序转换成可执行文件，并在没有Python环境的情况下运行。