14.Python打包工具- PyInstaller

源码地址：https://github.com/pyinstaller/pyinstaller

PyInstaller是一个强大的打包工具，通过它，可以将Python 项目及其项目所有的依赖都打包到一个独立的应用包中，这个应用包可以在没有Python 环境以及其他依赖的情况下独立运行。

环境要求

如果操作系统是Windows，PyInstaller需要运行在Windows 8及以上版本。PyInstall可以创建视窗应用（非控制台视窗）。

如果操作系统是MacOS，PyInstaller在macOS 10.15(Catalina)或更新版本上运行。它可以构建图形窗口应用程序（不使用终端窗口的应用程序）。PyInstaller构建的应用程序与运行它的macOS版本以及以下版本兼容。它可以在任何一种架构的macOS机器上构建x86_64、arm64或混合通用二进制文件。

如果操作系统是GNU/Linux，PyInstaller需要ldd终端应用程序来发现每个应用所依赖的库或共享库。它通常在发行包glibc或libc-bin中找到。它还需要objdump终端应用程序从对象文件中提取信息，objcopy终端应用程序将数据附加到引导程序中。它们通常在发行包binutils中找到。

如果操作系统是AIX，Solaris，FreeBSD或OpenBSD，用户报告在这些平台上成功运行PyInstaller，但没有在这些平台上进行测试。需要使用ldd和objdump命令。

使用参数

pyinstaller命令的语法是：

Pyinstaller [options] script [script…]| specfile

在最简单的情况下，将当前目录设置为程序myscript.py的位置并执行：

pyinstaller myscript.py

首先，PyInstaller根据脚本myscript.py分析，找到所有导入和所需要的模块，然后：

• 在与脚本相同的文件夹中编写myscript.spec。

• 如果脚本不存在，则在与脚本相同的文件夹中创建build文件夹。

• 在build文件夹中写入一些日志文件和工作文件。

• 如果脚本不存在，则在与脚本相同的文件夹中创建dist文件夹。

• 在dist目录中创建和写入myscript可执行文件夹。

在dist文件夹中，你可以找到你要分发的应用包。

通常在命令行上指定一个脚本名（如上的myscript.py）即可；但如果您指定了更多，那么所有指定都将被分析并包含到输出中。如果提供了与第一个脚本名称相同的spec文件和可执行文件夹或文件。那么它的代码在运行时则首先执行。

对于某些用途，您可以编辑myscript.spec的内容。然后使用PyInstaller运行与脚本同名的spec文件而不是脚本：

pyinstaller myscript.spec

myscript.spec文件包含了在使用脚本文件作为参数运行pyinstaller（或pyi-makespec）时所用选项的大部分信息。在使用spec文件作为参数运行pyinstaller时，通常不需要指定任何选项。在使用spec文件构建时，只有少数命令行选项有影响。

例如，您可以提供脚本或规范文件的路径：

pyinstaller options… ~/myproject/source/myscript.py

位置参数

• scriptname：Python 脚本文件名或者spec文件名。如果指定了.spec文件，则大多数选项都是不必要的，并且会被忽略。

可选参数

生成什么

捆绑什么？在哪搜索

如何生成

Windows和Macos专用参数

Windows专用参数

MacOS专用参数

很少用的特殊参数

spec文件

创建spec

当我们执行类似命令行pyinstaller options.. myscript.py时，PyInstaller做的第一件事是构建一个spec（specification）文件myscript.spec。该文件存储在--specpath参数指定的目录中，如果未指定，默认是当前目录。

PyInstaller通过spec文件配置，对给定脚本名和提供的大多数选项进行编码。

spec文件实际上是可执行的Python代码，PyInstaller通过执行spec文件的内容来构建应用程序。

对于PyInstaller的许多用途，您不需要检查或修改spec文件。通常将足够的信息（例如隐藏的导入）作为选项提供给Pyinstaller命令并让它运行。

在四种情况下，修改spec文件是有用的：

• 当你想把数据文件和应用捆绑在一起时。

• 当您想要包含PyInstaller无法从其他源获取到的运行时库（.dll或.so文件）时。

• 当您想要向可执行文件添加Python运行时选项时。

• 当您想要使用合并的公共模块创建多程序包时。

使用下面的命令可以创建一个spec文件：

pyi-makespec options name.py [other scripts …]

上例中[other scripts …]选项与前面的Pyinstaller命令的选项相同。该命令创建name.spec文件，但不继续构建可执行文件。

在你创建了一个spec文件并根据需要修改它之后，你通过将spec文件传递给Pyinstaller命令来构建应用程序：

pyinstaller options name.spec

在创建spec文件时，大多数命令选项都在spec文件中设置。从spec文件构建时，不能更改这些选项。如果它们是在命令行中给出的，它们将被忽略，并被spec文件中的选项所替换。

当从spec文件构建时，只有以下命令行选项有效：--upx-dir、--distpath、--workpath、--noconfirm、--clean和-log-level。

spec文件基本操作

在PyInstaller创建一个spec文件，将该spec文件（可不是脚本文件）作为命令行参数传入：

pyinstaller myscript.spec

PyInstaller命令将spec文件作为代码执行。绑定的应用就是通过执行spec文件创建的。下面是一个简短的例子，一个最小的，只有一个文件夹的应用程序的规范文件：

a = Analysis(['minimal.py'], pathex=['/Developer/PItests/minimal'], binaries=None, datas=None, hiddenimports=[], hookspath=None, runtime_hooks=None, excludes=None) pyz = PYZ(a.pure) exe = EXE(pyz,... ) coll = COLLECT(...)

上例中，通过spec文件的配置创建Analysis、pyz、exe和coll四个类实例。

1. Analysis创建时以脚本名称列表['minimal.py']作为输入，分析所有导入和其他依赖项，然后返回结果对象（即a）。结果对象属性记录了这些依赖：

   • scripts属性：命令行中传入的 Python 脚本；
   • pure属性：脚本代码中所须的纯 Python 模块；
   • pathx属性：用于搜索导入的路径列表（如使用PYTHONPATH），包括由--paths选项给出的路径。
   • binaries属性：脚本所需的非 Python 模块，包括由--add-binary选项给出的名称序列；
   • data属性：应用程序中包含的非二进制文件，包括由--add-data选项给出的名称序列。

2. pyz实例用来操作.pyz归档文件，它包含了a.pure文件中的所有Python模块

3. exe实例是依托分析的脚本和pyz归档文件构建的。该对象用来创建可执行文件。

4. coll实例根据所有其他部分来创建输出文件夹。

在单文件模式下，不需要调用COLLECT；EXE实例接收所有的脚本、模块和二进制文件。

修改spec文件以将附加值传递给Analysis和EXE。

添加文件到绑定

要将文件添加到包中，您需要创建一个描述文件的列表提供给Analysis调用。

当捆绑到单文件夹时，添加的数据文件被复制到可执行文件所在的文件夹中。

当您绑定到单可执行文件时，添加的文件的副本被压缩到可执行文件中，并在执行之前扩展到_MEIxxxxxx临时文件夹。这意味着当应用程序结束时，单可执行文件对添加的文件所做的任何更改都将丢失。

添加数据文件

可以使用--add-data命令选项将数据文件添加到包中，或者将它们作为列表添加到spec文件中。

在spec文件中提供一个描述文件的列表，作为Analysis的datas=参数的值。数据文件列表是一个元组列表。每个元组有两个值，这两个值都必须是字符串：

• 第一个参数指定当前系统中源文件路径或源文件路径列表。

• 第二个参数指定目标路径，即将指定的源文件复制到的目的文件夹。

例如，要在单目录应用的顶层添加一个README文件，你可以这样修改spec文件：

a = Analysis(... datas=[ ('src/README.txt', '.') ], ... )

如果使用命令行，例子如下：

pyinstaller --add-data "src/README.txt:." myscript.py

您已经使datas=参数成为一个单项列表。该项是一个元组，其中第一个字符串表示现有文件是src/README.txt。该文件将被查找（相对于spec文件的位置）并复制到绑定应用的顶层。

字符串可以使用 “/” 或 “\” 作为路径分隔符。您可以使用 “glob” 缩写来指定输入文件。例如，要包含某个文件夹中的所有.mp3文件：

a = Analysis(... datas= [ ('/mygame/sfx/*.mp3', 'sfx' ) ], ... )

所有在/mygame/sfx文件夹中的.mp3文件将被复制到绑定应用程序中名为sfx的文件夹中。

如果您在单独的声明中增加的文件列表定义，则spec文件更具可读性：

added_files = [ ( 'src/README.txt', '.' ), ( '/mygame/sfx/*.mp3', 'sfx' ) ] a = Analysis(... datas = added_files, ... )

你也可以使用通配符来圈定所有能匹配的内容：

added_files = [ ( 'src/README.txt', '.' ), ( '/mygame/data', 'data' ), ( '/mygame/sfx/*.mp3', 'sfx' ) ]

如上例，/mygame/data文件夹将复制到绑定的data目录下。

添加模块中的数据文件

如果要添加的数据文件包含在Python模块中，则可以使用pkgutil.get_data() 检索它们。

例如，假设应用程序的这一部分是一个名为helpmod的模块。模块下有脚本和数据文件，如下：

helpmod __init__.py helpmod.py help_data.txt

因为在脚本中包含有import helpmod这样的语句，PyInstaller会在绑定的应用中创建这个文件夹。但是，它只处理包含.py文件。数据文件help_data.txt不会被自动包含。要使它也被包含，你需要在spec文件中添加一个数据元组：

a = Analysis(... datas= [ ('helpmod/help_data.txt', 'helpmod' ) ], ... )

当脚本执行时，通过使用其配置的基本文件夹路径找到help_data.txt，如前一节所述。另外，该数据文件作为模块的一部分，因此您也可以使用标准库函数pkgutil.get_data() 检索其内容：

import pkgutil help_bin = pkgutil.get_data( 'helpmod', 'help_data.txt' )

这将以二进制字符串的形式返回help_data.txt文件的内容。如果它实际上是字符，你必须对其解码：

help_utf = help_bin.decode('UTF-8', 'ignore')

添加二进制文件

💡小提示

二进制文件指的是动态链接库、共享对象文件等，PyInstaller将在这些文件中搜索更多的二进制依赖项。像图像和pdf这样的文件应该放入data中。

您可以使用--add-binary命令参数将二进制文件添加到包中，或者将它们作为列表添加到spec文件中。在spec文件中，创建一个描述所需文件的元组列表。将元组列表赋值给Analysis的binaries=参数。

添加二进制文件的工作方式与添加数据文件类似。如添加二进制文件中所述，每个元组应该有两个值：

• 第一个参数指定当前系统中文件的位置。

• 第二个参数指定文件复制的目标文件夹。

通常，PyInstaller通过分析导入的模块来了解.so和.dll库，但有时不清楚是否导入了模块；在这种情况下，使用--hidden-import命令参数。但即使这样也可能找不到所有的依赖关系。

假设您有一个C或Pythone C API的模块special_ops.so， 您的程序导入了special_ops， 且PyInstaller查找并包含special_ops.so。但假如special_ops.so使用到了libiodbc.2.dylib库，这时，PyInstaller是找不到找不到libiodbc.2.dylib依赖项。你可以这样把它添加到绑定中：

a = Analysis(... binaries=[ ( '/usr/lib/libiodbc.2.dylib', '.' ) ], ...

或者使用命令行：

a = Analysis(... binaries=[ ( '/usr/lib/libiodbc.2.dylib', 'vendor' ) ], ...

与数据文件一样，如果要添加多个二进制文件，为了提高可读性，可以在单独的语句中创建列表，并将名称传递列表。

使用TOC添加文件

Analysis对象生成几个内容表格（Table of Contents，TOC）列表，这些列表提供了要收集的文件信息。根据文件的类型或功能，将这些文件分组到不同的列表中，例如：

• Analysis.scripts: 应用脚本集合
• Analysis.pure: 纯 Python 模块集合
• Analysis.binaries: 二进制扩展模块（如.dll或.so等）、共享动态链接库集合
• Analysis.datas: 数据文件集合

生成的TOC列表被传送到spec文件中的各个构建目标，如PYZ、EXE和COLLECT。

每个TOC列表的每项是三个元素的元组(dest_name, src_name , typecode)，其中dest_name是目标文件名（即冻结应用程序中的文件名），src_name是源文件名（或收集文件的路径），typecode是一个表示文件（或条目）类型的字符串。

在内部，PyInstaller包含许多typecode值，但对于正常情况，你只需要知道这些：

相对于顶级应用程序目录，目标名称对应于冻结应用程序中的最终名称。它可能包含路径元素，例如extras/mydata.txt。

假定BINARY和EXTENSION类别的组成项表示包含可加载的可执行代码的文件，例如动态库。通常，EXTENSION用于表示Python扩展模块，例如由Cython编译的模块。这两种类别的处理方式相同；PyInstaller扫描它们以寻找额外的链接时依赖项，并收集发现的任何依赖项。在某些操作系统上，二进制文件和扩展需要经过额外的处理（例如针对链接时间依赖性的路径重写和macOS上的代码签名）。

在Analysis生成的TOC列表传递给构建目标之前，可以在spec文件中修改它们，以包含额外的条目（最好是通过二进制文件或Analysis的数据参数传递要包含的额外文件）或删除不需要的条目。

然而，由于定义松散和语义冲突导致TOC类的不足，TOC类的使用已被弃用。TOC列表现在是普通列表的实例，PyInstaller执行显式列表（条目重复删除）。显式规范化在Analysis实例化结束时执行，此时列表存储在类属性中（例如Analysis.datas和Analysis.binaries)。类似地，一旦构建目标（EXE、PYZ、PKG、COLLECT、BUNDLE）将输入TOC列表合并到最终列表中，也将执行显式列表规范化。

使用Tree类

Tree类提供了一种方便的方法来创建TOC列表：

Tree(root, prefix=run-time-folder, excludes=string_list, typecode=code | 'DATA' )

• root参数是一个字符串，表示到目录的路径。它可以是绝对的，也可以是相对于spec文件所在目录的。

• prefix参数是可选的，是应用程序目录中要收集文件的子目录的名称。如果不指定或设置为None，则文件将被收集到顶级应用程序目录中。

• exclude参数也是可选的，是一个字符串列表；用来匹配root中需要剔除的文件。列表中的组合项可以是：

  • 用来排除具有此基本名称的文件或文件夹的匹配名
  • 一个glob模式（如*.ext），匹配的文件将被排除

• typecode参数也是可选的，指定TOC类型码，该值分配给TOC列表中的所有条目。默认值是DATA，适用于大多数情况。

extras_toc = Tree('../src/extras', prefix='extras', excludes=['tmp', '*.pyc'])

这将创建extras_toc作为TOC列表，其中包含来自相对路径./src/extras的所有文件，省略那些位于名为TMP的文件夹中的所有问价或具有.pyc扩展名的文件。这个TOC中的每个元组有：

• dest_name的格式为：file:extras/{filename}。

• src_name对应于.. /src/extras（相对于spec文件所在目录）目录下的文件的完整绝对路径。

• typecode类型码的默认用类型DATA。

下面案例显示创建一个列一些二进制模块的TOC的示例：

cython_mods = Tree('..src/cy_mods', excludes=['*.pyx', '*.py', '*.pyc'], typecode='EXTENSION')

创建一个TOC列表，其中包含cy_mods目录中每个文件，除了扩展名为.pyx、.py或.pyc的文件。TOC中的元组表示如下：

• 与dest_name指定的名字相匹配的文件（所有文件都收集在顶级应用程序目录中）。

• src_name对应于../src/cy_mods目录下的所有的文件绝对路径。

• 类型码为EXTENSION（也可以使用BINARY类型码）。

指定 Python 解释器选项

pyinstaller冻结的应用在嵌入Python解释器中独立运行时，不能采用典型的方式将选项传递给Python解释器，包括：

• 冻结的应用程序与目标系统上存在的python环境完全隔离，通过环境变量（如PYTHONUTF8和PYTHONHASHSEED）获取参数值不可能；

• 因为命令行参数是为应用程序保留的，不能通过命令行参数（如-v和-o）。

因此，PyInstaller提供了一个选项，通过其自己的options机制为应用程序的Python解释器指定永久运行时选项。要传递运行时选项，需创建一个由三元素元组组成的列表：(' option string ', None, ' option ')，并将其作为附加参数传递给EXE，在关键字参数之前。选项元组的第一个元素是选项字符串，第二个总是None，第三个总是option。

spec文件的一个示例，修改为指定两个运行时选项：

options = [ ('v', None, 'OPTION'), ('W ignore', None, 'OPTION'), ] a = Analysis( ... ) ... exe = EXE( pyz, a.scripts, options, # <-- the options list, passed to EXE exclude_binaries=... ... )

该机制支持以下选项：

• v或verbose：增加sys.flags.Verbose的值，该值影响模块每次初始化时将消息写入标准输出。这个选项相当于Python的-v命令行选项。当通过PyInstaller自己的--debug imports选项启用详细导入时，它会自动启用。

• u或unbuffered：启用未缓冲的标准输出和标准错误。相当于Python的-u命令行选项。

• O或optimize：增加sys.flags.optimize的值。相当于Python的-O命令行选项。

• W <arg>：通过 Python 的W-options来控制警告消息。

• X <arg>：通过 Python 的X-options传递。utf8和dev x-options控制UTF-8模式和开发者模式，由PyInstaller的bootloader显式解析并在解释器预初始化期间使用；其余的x-options只是传递给解释器配置。

• hash_seed=<value>：通过冻结应用程序使用该值去设置 Python 的哈希种子。相当于PYTHONHASHSEED环境变量。

下面举例说明这些语法：

options = [ # Warning control ('W ignore', None, 'OPTION'), # disable all warnings ('W ignore::DeprecationWarning', None, 'OPTION') # disable deprecation warnings # UTF-8 mode; unless explicitly enabled/disabled, it is auto enabled based on locale ('X utf8', None, 'OPTION), # force UTF-8 mode on ('X utf8=1', None, 'OPTION), # force UTF-8 mode on ('X utf8=0', None, 'OPTION), # force UTF-8 mode off # Developer mode; disabled by default ('X dev', None, 'OPTION), # enable dev mode ('X dev=1', None, 'OPTION), # enable dev mode # Hash seed ('hash_seed=0', None, 'OPTION'), # disable hash randomization; sys.flags.hash_randomization=0 ('hash_seed=123', None, 'OPTION'), # hash randomization with fixed seed value # Force enable/disable GIL in python >= 3.13 built with Py_DISABLE_GIL / free-threading option (PEP-703) ('X gil=1', None, 'OPTION), # force-enable GIL ('X gil=0', None, 'OPTION), # force-disable GIL ]

设置SPLASH目标

要让bootloader显示启动屏幕，必须在构建时调用启动目标；使用命令行选项--splash IMAGE_FILE。创建spec文件时，可以添加这个类。默认情况下，禁用显示可选文本的选项（text_pos=None）。Splash目标看起来是这样的：

a = Analysis(...) splash = Splash('image.png', binaries=a.binaries, datas=a.datas, text_pos=(10, 50), text_size=12, text_color='black')

Splash将启动屏幕所需的资源捆绑到一个文件中，该文件将包含在CArchive中。

Splash有两个输出，一个是它本身，另一个存储在Splash .binaries中。两者都需要传递给其他构建目标，以便启用启动屏幕。要在单文件应用程序中使用闪屏，请遵循以下示例：

a = Analysis(...) splash = Splash(...) # onefile exe = EXE(pyz, a.scripts, splash, # <-- both, splash target splash.binaries, # <-- and splash binaries ...)

为了在单目录应用程序中使用启动屏幕，只需要做一个小的更改。splash.binaries属性必须移动到COLLECT目标中，因为splash二进制文件不需要包含在可执行文件中：

a = Analysis(...) splash = Splash(...) # onedir exe = EXE(pyz, splash, # <-- splash target a.scripts, ...) coll = COLLECT(exe, splash.binaries, # <-- splash binaries ...)

在Windows/macOS上，支持逐像素透明的图像。这允许非矩形启动屏幕图像。在Windows上，图像的透明边界是硬切割的，这意味着不支持褪色的透明值。Linux上没有针对非矩形窗口的通用实现，因此不支持具有每像素透明度的图像。

可用的全局变量

当spec文件执行时，它可以访问一组有限的全局名称。这些名称包括PyInstaller定义的类：Analysis，BUNDLE，COLLECT，EXE，MERGE，PYZ，TOC，Tree和Splash，这些在前面的章节中讨论过。

其他全局变量包含有关构建环境的信息：