【Python】使用PyInstaller打包python程序文档翻译

PyInstaller打包python程序

使用 PyInstaller

渣翻自官方文档

pip install pyinstaller

使用pyinstaller命令的方法如下：

pyinstaller [options] script [script ...] | specfile

最简单的情况下，进入到你的程序myscript.py所在的文件夹下，执行：

pyinstall myscript.py

PyInstaller分析mycript.py，然后：

• 在所在文件夹下写文件mycript.spec
• 在所在文件夹下创建文件夹build
• 在build中写入一些日志文件和工作文件
• 在所在文件夹下创建文件夹dist
• 在dist中写入mycript可执行文件

在dist文件夹中，可以找到打包的应用程序。

常规选项

-h, --help	显示帮助信息并退出
-v, --version	显示程序版本并退出
–distpath DIR	打包应用输出路径
–workpath WORKPATH	存放日志、工作文件等的工作路径
-y, --noconfirm	无需询问直接覆盖输出路径 (默认: SPECPATH/dist/SPECNAME)
–upx-dir UPX_DIR	UPX工具路径
-a, --ascii	不包含unicode编码支持(默认:如果可用的话包括在内)
–clean	在构建之前清除PyInstaller缓存并删除临时文件
–log-level LEVEL	构建时控制台消息中的大量细节。级别可以是TRACE, DEBUG, INFO, WARN, ERROR, CRITICAL(默认:INFO)

生成内容选项

-D, --onedir	创建一个包含可执行文件的单文件夹包(默认)
-F, --onefile	创建一个打包的可执行文件
–specpath DIR	指定保存spec文件的文件夹(默认:当前目录)
-n NAME, --name NAME	分配给打包的应用程序和规格文件的名称(默认:第一个脚本的basename)

打包内容和所在位置选项

–add-data <SRC;DEST or SRC:DEST>	要添加到可执行文件中的其他非二进制文件或文件夹。路径分隔符是平台特定的，os.pathsep(在Windows上为;，在大多数unix系统上为:)中使用。此选项可多次使用。
–add-binary <SRC;DEST or SRC:DEST>	要添加到可执行文件中的其他二进制文件。有关更多细节，请参阅–add-data选项。此选项可多次使用。
-p DIR, --paths DIR	搜索导入的路径(比如使用PYTHONPATH)。允许使用多个路径，用’:'分隔，或者多次使用此选项
–hidden-import MODULENAME, --hiddenimport MODULENAME	在脚本代码中不可见的导入的名字。此选项可多次使用。
–additional-hooks-dir HOOKSPATH	搜索 hooks 的附加路径。此选项可多次使用。
–runtime-hook RUNTIME_HOOKS	自定义 runtime hook 文件的路径。runtime hook 是与可执行文件打包在一起的代码，它在任何其他代码或模块之前执行，以设置运行时环境的特殊特性。此选项可多次使用。
–exclude-module EXCLUDES	可选模块或包(Python名，而不是路径名)将被忽略(就像没有找到它一样)。此选项可多次使用。
–key KEY	用于加密Python字节码的密钥。

生成过程选项

-d <all,imports,bootloader,noarchive>, --debug <all,imports,bootloader,noarchive>	提供协助调试冻结的应用程序。可以多次提供此参数，以选择下列选项中的几个。 - all: 以下所有的选项 - import: 为底层Python解释器指定-v选项，使其在每次初始化模块时打印一条消息，显示加载模块的位置(文件名或内置模块)。见https://docs.python.org/3/using/cmdline.html#id4. - bootloader: 告诉引导加载程序在初始化和启动打包的应用程序时发出进度消息。用于诊断缺少导入的问题。 - noarchive: 不将所有冻结的Python源文件作为归档文件存储在结果可执行文件中，而是将它们作为文件存储在结果输出目录中。
-s, --strip	对可执行文件和共享库应用 symbol-table strip (不推荐在Windows中使用)
–noupx	不要使用UPX，即使它是可用的(在Windows和*nix工作不同)
–upx-exclude FILE	当使用upx时，不压缩二进制文件。如果upx在压缩过程中破坏了某些二进制文件，通常会使用这种方法。FILE是不带路径的二进制文件的文件名。此选项可多次使用。

Windows 和 Mac OS X 的特定选项

-c, --console, --nowindowed	为标准i/o打开一个控制台窗口(默认)。在Windows上，如果第一个脚本是’pyw’文件，这个选项将没有作用。
-w, --windowed, --noconsole	Windows和Mac OS X: 不为标准i/o提供控制台窗口。在Mac OS X上，这也会触发创建OS X .app包。在Windows上，如果第一个脚本是’pyw’文件，将设置此选项。这个选项在*NIX系统中被忽略。
-i <FILE.ico or FILE.exe,ID or FILE.icns>, --icon <FILE.ico or FILE.exe,ID or FILE.icns>	FILE.ico: 将该图标应用到Windows可执行文件。FILE.exe,ID: 从exe文件中提取对应ID的图标。FILE.icns: 将图标应用到Mac OS X上的.app包

Windows 的特定选项

–version-file FILE	从FIFE中添加版本资源到exe文件中
-m <FILE or XML>, --manifest <FILE or XML>	添加清单FILE或XML到exe
-r RESOURCE, --resource RESOURCE	向Windows可执行文件添加或更新资源。资源是1到4个项目，FILE[,TYPE[,NAME[,LANGUAGE]]。文件可以是一个数据文件或exe/dll。对于数据文件，至少必须指定类型和名称。语言默认值为0，也可以指定为通配符*，以更新给定类型和名称的所有资源。对于exe/dll文件，如果类型、名称和语言被省略或指定为通配符*，文件中的所有资源将被添加/更新到最终的可执行文件中。此选项可多次使用。
–uac-admin	使用此选项将创建一个清单，该清单将在应用程序重启时请求提升。
–uac-uiaccess	使用此选项允许升级后的应用程序与远程桌面一起工作。

Windows 并排程序集搜索选项(高级)

–win-private-assemblies	绑定到应用程序中的任何共享程序集都将被更改为私有程序集。这意味着将始终使用这些程序集的确切版本，而在系统级别上安装在用户机器上的任何更新版本都将被忽略。
–win-no-prefer-redirects	在搜索要绑定到应用程序中的共享程序集或私有程序集时，PyInstaller将不喜欢遵循重定向到新版本的策略，而会尝试绑定程序集的确切版本。

Mac OS X 的特定选项

–osx-bundle-identifier BUNDLE_IDENTIFIER	Mac OS X .app bundle identifier被用作代码签名的默认唯一程序名。通常的形式是用反向DNS表示法表示的层次名称。例如:com.mycompany.department.appname(默认:第一个脚本的basename)

很少使用的特殊选项

–runtime-tmpdir PATH	在其中提取库和支持文件在一个文件模式。如果提供了这个选项，引导加载程序将忽略运行时OS定义的任何模板文件夹位置。_meixxxxxx文件夹将在这里创建。请只在您知道您在做什么的情况下使用这个选项。
–bootloader-ignore-signals	告诉引导加载程序忽略信号，而不是将它们转发给子进程。这在以下情况下很有用，例如，一个监督进程同时给引导装载程序和子进程发出信号(例如，通过进程组)，以避免给子进程发送两次信号。

简化命令

由于选项众多，完整的pyinstaller命令可能会变得非常长。在开发脚本时，您将反复运行相同的命令。您可以将命令放在一个shell脚本或批处理文件中，使用行连续符使其可读。例如，在GNU/Linux中:

pyinstaller --noconfirm --log-level=WARN \
    --onefile --nowindow \
    --add-data="README:." \
    --add-data="image1.png:img" \
    --add-binary="libfoo.so:lib" \
    --hidden-import=secret1 \
    --hidden-import=secret2 \
    --upx-dir=/usr/local/share/ \
    myscript.spec

或者在Windows中，使用鲜为人知的BAT文件续行:

pyinstaller --noconfirm --log-level=WARN ^
    --onefile --nowindow ^
    --add-data="README;." ^
    --add-data="image1.png;img" ^
    --add-binary="libfoo.so;lib" ^
    --hidden-import=secret1 ^
    --hidden-import=secret2 ^
    --icon=..\MLNMFLCN.ICO ^
    myscript.spec

从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字节码优化机制是如何工作的。当使用-O时，__debug__被设置为False, assert语句被从字节码中删除。-OO标志额外地删除文档字符串。

使用此特性不仅会影响主脚本，还会影响PyInstaller包含的所有模块。如果您的代码(或脚本导入的任何模块)依赖于这些特性，您的程序可能会中断或有意外的行为。

PyInstaller可以以Python模块的形式运行，并带有Python优化标志(-O或-OO)，而不是使用PyInstaller命令:

# run with basic optimizations
python -O -m PyInstaller myscript.py

# also discard docstrings
python -OO -m PyInstaller myscript.py

或者，通过显式地将 PYTHONOPTIMIZE 环境变量设置为一个非零值:

# Unix
PYTHONOPTIMIZE=1 pyinstaller myscript.py

# Windows
set PYTHONOPTIMIZE=1 && pyinstaller myscript.py

您可以使用PyInstaller命令提供的任何PyInstaller选项。例如:

python -O -m PyInstaller --onefile myscript.py

另外，你也可以使用pyinstaller的路径:

python -O /path/to/pyinstaller myscript.py

使用UPX

UPX是一个可用于大多数操作系统的免费实用程序。UPX压缩可执行文件和库，使它们更小，有时会小得多。UPX可用于大多数操作系统，可以压缩大量可执行文件格式。有关下载，请参阅UPX主页，以及支持的可执行格式列表。

一个压缩的可执行程序被包装在UPX启动代码中，当程序启动时，UPX启动代码动态地解压缩程序。解压后，程序正常运行。在一个已经被upx压缩的PyInstaller单文件可执行文件的情况下，完整的执行顺序是:

• 压缩程序在UPX解压代码中启动。
• 在解压之后，程序执行PyInstaller引导加载程序，它为Python创建一个临时环境。
• Python解释器执行你的脚本。

PyInstaller在执行路径或使用--UPX-dir选项指定的路径上查找UPX。如果UPX存在，PyInstaller将它应用到最终可执行文件，除非指定了--noupx选项。UPX经常与PyInstaller输出一起使用，通常没有问题。

加密Python字节码

要加密存储在包中的Python字节码模块，需要在命令行上传递 --key=key-string 参数。

为了工作，你需要运行:

pip install pyinstaller[encryption]

key-string是一个包含16个字符的字符串，用于在Python字节码存储到可执行文件中的归档文件之前对每个文件进行加密。

该特性在内部使用tinyaes模块进行加密。

确定提取位置

在极少数情况下，当您打包到单个可执行文件时(请参阅打包到一个文件以及单文件程序的工作方式)，您可能希望在编译时控制临时目录的位置。这可以使用--runtime-tmpdir选项来完成。如果提供了这个选项，引导加载程序将忽略运行时OS定义的任何临时文件夹位置。请只在您知道您在做什么的情况下使用这个选项。

多平台支持

如果您的应用程序只适用于OS和Python的一种组合，那么只需像安装其他包一样安装PyInstaller，并在您的常规开发设置中使用它。

支持多python环境

当你需要将你的应用在一个操作系统中打包，但却适用于不同版本的Python和支持库——例如，Python 3.6版本和Python 3.7版本;或者使用Qt4的支持版本和使用Qt5的开发版本——我们建议您使用venv。使用venv，您可以维护Python和已安装包的不同组合，并轻松地从一种组合切换到另一种组合。这些被称为虚拟环境或简称venvs。

• 使用venv创建您需要的任意多个不同的开发环境，每个环境都有其Python和已安装包的独特组合。
• 在每个虚拟环境中安装PyInstaller。
• 使用PyInstaller在每个虚拟环境中构建应用程序。

注意，当使用venv时，PyInstaller命令的路径是:

• Windows: ENV_ROOT\Scripts
• Others: ENV_ROOT/bin

在Windows下，pip-Win包使得设置不同的环境和在它们之间切换变得特别容易。在GNU/Linux和Mac OS下，可以在命令行切换环境。

有关Python虚拟环境的更多信息，请参阅PEP 405和关于虚拟环境和包的官方Python教程。

支持多操作系统

如果你需要在多个操作系统上发布你的应用，例如Windows和Mac OS X，你必须在每个平台上安装PyInstaller，并在每个平台上分别捆绑你的应用。

您可以使用虚拟化在单台机器上完成此任务。免费的virtualBox或付费的VMWare和Parallels都可以让你以“客人”的身份运行另一个完整的操作系统。您为每个“guest”操作系统设置了一个虚拟机。在其中安装Python、应用程序所需的支持包和PyInstaller。

像NextCloud这样的文件同步和共享系统对于虚拟机非常有用。在每个虚拟机中安装同步客户端，它们都链接到您的同步帐户。在同步文件夹中保存一份脚本的副本。然后在任何虚拟机上运行PyInstaller:

cd ~/NextCloud/project_folder/src # GNU/Linux, Mac -- Windows similar
rm *.pyc # get rid of modules compiled by another Python
pyinstaller --workpath=path-to-local-temp-folder  \
            --distpath=path-to-local-dist-folder  \
            ...other options as required...       \
            ./myscript.py

PyInstaller从通用同步文件夹中读取脚本，但将其工作文件和打包的应用程序写入虚拟机本地的文件夹中。

如果你在多个平台上共享相同的主目录,例如GNU / Linux和OS X,您将需要将PYINSTALLER_CONFIG_DIR环境变量设置为不同的值在每个平台上否则PyInstaller可能缓存文件为一个平台和在其他平台上使用它们,因为在默认情况下它使用您的主目录的子目录缓存位置。

据说可以使用免费的Wine环境在GNU/Linux下为Windows进行交叉开发。需要更多的细节，见如何贡献。

捕获Windows版本数据

Windows应用程序可能需要版本资源文件。版本资源包含一组数据结构，其中一些包含二进制整数，另一些包含字符串，描述可执行文件的属性。有关详细信息，请参阅Microsoft版本信息结构页面。

版本资源是复杂的，一些元素是可选的，另一些是必需的。当您查看属性对话框的version选项卡时，所显示的数据和资源结构之间没有简单的关系。出于这个原因，PyInstaller包含pyi-grab_version命令。使用任何具有版本资源的Windows可执行文件的完整路径名调用:

pyi-grab_version executable_with_version_resource

该命令以可读的形式将表示版本资源的文本写入标准输出。您可以从控制台窗口复制它或将其重定向到一个文件。然后您可以编辑版本信息以使其适应您的程序。使用pyi-grab_version可以找到显示所需信息的可执行文件，复制它的资源数据，并修改它以适应您的包。

版本文本文件用UTF-8编码，可能包含非ascii字符。(Unicode字符允许出现在版本资源字符串字段中。)请确保以UTF-8格式编辑和保存文本文件，除非您确定它只包含ASCII字符串值。

你的编辑版本文本文件可以用–version-file=选项指定到pyinstaller或pyi-makespec。文本数据转换为版本资源并安装在捆绑的app中。

在版本资源中有两个64位二进制值:FileVersion和ProductVersion。在版本文本文件中，这些元素以四元组的形式给出，例如:

filevers=(2, 0, 4, 0),
prodvers=(2, 0, 4, 0),

每个元组的元素表示从最高到最低的16进制值。例如，值(2,0,4,0)解析为十六进制的0002000000040000。

你也可以使用pyi-set_version命令在绑定应用创建后从文本文件中安装版本资源:

pyi-set_version version_text_file executable_file

pyi-set_version实用程序读取由pyi-grab_version编写的版本文本文件，将其转换为版本资源，并将该资源安装到指定的executable_file中。

对于高级应用，请检查由pyi-grab_version编写的版本文本文件。你会发现创建VSVersionInfo对象的是Python代码。VSVersionInfo的类定义在utils/win32/versioninfo.py的PyInstaller分发文件夹中找到。您可以编写一个导入versioninfo的程序。在这个程序中，你可以eval一个版本信息文本文件的内容来产生一个VSVersionInfo对象。您可以使用该对象的. toraw()方法以二进制形式生成版本资源。或者可以对对象应用unicode()函数来重新生成版本文本文件。

构建Mac OS X应用程序包

略，查看原文

平台特定笔记

GNU/Linux

Making GNU/Linux Apps Forward-Compatible

略，查看原文

Windows

对于针对Windows < 10的Python >= 3.5，开发人员需要特别注意包含Visual c++运行时.dll: Python 3.5使用Visual Studio 2015运行时，它已经被重命名为“Universal CRT”，并成为Windows 10的一部分。对于从Windows 8.1到Windows Vista，有Windows更新包，它们可能安装在目标系统中，也可能没有安装。所以你有以下选项:

1. 在Windows 7构建，据说可以工作。
2. 将一个VCRedist包(可重新发布的包文件)包含到应用程序的安装程序中。这是微软推荐的方法，见上面提到的链接“使用通用CRT的软件分发”，数字2和3。
3. 安装Windows 10的Windows软件开发工具包(SDK)，展开.spec文件以包含所需的dll，请参阅上面链接中的“使用通用CRT的发布软件”，第6节。

如果你认为，PyInstaller应该自己做这个，请帮助改进PyInstaller。

Mac OS X

略，查看原文