SHUHARI 的博客

流光飞舞

PyInstaller 系列 - 基本用法

版权声明: 本博客所有内容除特殊说明外,均系原创,允许转载,但需注明来源。

这是本系列的第一篇,介绍 PyInstaller 的基础知识。

PyInstaller 是一个跨平台的 Python 应用打包工具,支持 Windows/Linux/MacOS 三大主流平台,能够把 Python 脚本及其所在的 Python 解释器打包成可执行文件,从而允许最终用户在无需安装 Python 的情况下执行你的程序。

PyInstaller 这个软件有几点容易引起误解的地方。首先,Installer 的名字可能会让用户望文生义地觉得这是个安装程序制作软件,类似 NSIS/WIX/InstallShield 等等,但实际上 PyInstaller 的作用是打包而不是安装。这可能是因为类似 py2exe 这样的好名字早就被其他项目用掉了吧。其次,PyInstaller 制作出来的执行文件并不是跨平台的。如果你需要分别为三大平台打包的话,那么你就要在三个平台上分别运行 PyInstaller,不要指望“一次编译,到处运行”(当然可以利用虚拟机简化多环境配置)。

介绍 PyInstaller 的资料在网上并不少,但大多是一些简单的运行和命令行说明,缺乏较为深入和系统性的讲解。同时,许多同学使用 PyInstaller 的过程中会遇到各种各样的问题,如果你不明白它的运行原理的话,有些问题就很难靠自己解决。这也是我编写本系列文章的原因。

本文系列中的实践部分,如无特别说明的话,均以 Windows 为系统平台————这应该也是大多数 PyInstaller 使用的环境。我自己的机器是 Windows 10,如果你用的是 Windows 7/8,也没有关系,PyInstaller 在 Windows 系列上的用法没什么不同。Mac 是另外一个较大的平台,但本文不会涉及,有问题的同学可以参考官方手册中针对 Mac 平台的特别说明。此外,现在已经是 2018 年,故本文不会考虑 Python 2.x 系列的兼容问题。

接下来介绍 PyInstaller 的安装和运行。

安装 PyInstaller

Python 3 以上版本安装 PyInstaller 最方便的方法当然是通过 PIP。直接运行如下命令即可:

pip install PyInstaller

然后等待安装结束。PyInstaller 会安装一些相关的库,例如在 Windows 下会同时安装 pypiWin32(pywin32的更新版本)。

可以用如下命令确认 PyInstaller 安装成功:

pyinstaller --version
> 3.3.1

运行 PyInstaller

PyInstaller 最简单的运行形式,只需要指定作为程序入口的脚本文件。假定这个文件叫做 main.py:

pyinstaller main.py

运行之后,我们会看到目录中多了这些内容:

  • main.spec 文件,其前缀和脚本名相同。它本质上是一个 Python 文件,指定了打包时所需的各种参数,熟悉格式以后也可以手工修改,其角色类似于 setup.py;
  • build 子目录,其中存放打包过程中生成的临时文件。有几个文件需要关注一下:
  • warnxxxx.txt:该文件记录了生成过程中的警告/错误信息。在一切正常的情况下,该文件也可能包含若干类似 missing module 的信息,这些信息并不表示出错,但如果 PyInstaller 运行有问题的话,你就需要检查这个文件来获取错误的详细内容了。
  • xref-xxxx.html:该文件输出了 PyInstaller 分析脚本得到的模块依赖关系图。如果出现类似找不到模块的信息,你可以查找这个文件来获得一些线索。但该文件的内容比较庞大,一般情况下很少会直接使用它。
  • dist 子目录,存放生成的最终文件。如果使用单文件模式————后面会讲到),那么这里将只有单个执行文件;如果使用目录模式的话,那么这里还会有一个和脚本同名的子目录,其下才是真正的可执行文件(以及相关的其他附属文件)。双击可执行文件就会启动程序。

Dist 目录内容

以上是在我机器上生成的目录内容(部分)。可以发现,对于基本的应用程序来说,Python 解释器本体(pythonxx.dll)是其中的大头。当然程序文件(main.exe)体积也不小,不过同学们也不要被吓怕了——占用空间的都是一些恒定的 Bootstrapper 内容。当你继续增加代码时,文件体积只会以 KB 为单位缓慢增加,不会再有如此恐怖的增长了。此外就是一些操作系统相关的辅助文件(这里是 Windows 的 UCRT 库)。

PyInstaller 命令行选项

在上面的例子里,我们用最简单的方式使用了 PyInstaller。实际上 PyInstaller 有相当多的命令行开关,可以从各个方面调整打包过程的行为。用如下命令就能看到所有支持的开关项:

pyinstaller --help

由于可用的选项如此之多,这里并不会逐个讲解,只主要介绍经常使用的几个开关。其他选项的详细内容可以参考官方手册。

  • -y | --noconfirm 直接覆盖输出文件,而无需提示。在多次重复运行命令时可避免烦人的反复确认。

  • -D | --onedir 生成包含执行文件的目录(这是默认行为)

  • -F | --onefile 和上一个选项相对,生成单一的可执行文件。注意,这个选项会带来一些特殊的行为,并且我个人强烈地不推荐你使用这个选项。具体的原因我们在后面的文章中讨论。

  • -i | --icon [.ico | .exe | .icns] 为 Windows/Mac 平台的执行文件指定图标。如果是 .exe 的话,还可以在后面加上 ,id 参数来指定具体的图标ID。

  • --version-file [filename] 添加文件版本信息。后面我们会通过一个具体的例子说明其用法。

  • -c | --console | --nowindowed 通过控制台窗口运行程序 并且分配标准输入/输出,(默认行为)。

  • -w | --windowed | --noconsole 和上一个选项相反,不创建控制台窗口,也不分配标准输入/输出。它们主要用来运行 GUI 程序。需要说明的是,没有输入输出会给调试带来一定困难,因此即便你编写的是 GUI 程序,也建议在调试时禁用这个选项,在最终发布时再打开。

  • --add-data [file:dir] 添加数据文件。如果有多个文件需要添加的话,该选项可以出现多次。注意,文件参数的格式为文件名+输出目录名,用路径分隔符分割。路径分割符,从技术上来讲就是 os.pathsep,在 Windows 下使用 ;,其他系统下则使用 :。 如果输出到和脚本相同的目录,则使用 . 作为输出目录。

  • --add-binary [file:dir] 添加二进制文件,即运行程序所需的 .exe/.dll/.so 等。其选项格式和 --add-data 相同,不再赘述。

通过 Shell 脚本/批处理运行 PyInstaller

看到上述这么多命令,你应该可以想象,通过命令行输入这么多参数应该是一件多么痛苦的事情。这个问题有两个解决办法。第一,我们可以把需要的命令保存成 Shell/批处理脚本。第二,也可以通过运行 .spec 文件来达到同样的效果。目前,我们还没有介绍 .spec 文件的内容,作为示例,我们先使用第一个方法。

为了避免命令行过长,在脚本中最好是使用换行符。类 Unix 系统和 Windows 系统的换行符是不同的(此外也要注意路径分隔符的写法)。Linux 中一个脚本的例子大概是这样的:

pyinstaller --noconfirm --onedir --windowed \
    --add-data="README.txt:." \
    --add-data="sample.png:img" \
    --add-binary="mylib.dll:lib" \
    --icon="main.ico" \
    --version-file="version.txt" \
    main.py

而 Windows 版本则是这样:

pyinstaller --noconfirm --onedir --windowed ^
    --add-data="README.txt;." ^
    --add-data="sample.png;img" ^
    --add-binary="mylib.dll;lib" ^
    --icon="main.ico" ^
    --version-file="version.txt" ^
    main.py

使用 UPX 优化执行文件大小

有不少用户会觉得 PyInstaller 生成的文件太大,不便于发布。由于 Python 解释器本身的体积很难裁剪,所以 PyInstaller 提供了一个方案。如果 PyIntaller 在系统路径上发现了 UPX,那么它会用 UPX 来压缩执行文件。如果你确实有 UPX,但又并不希望裁剪的话,可以用--no-upx 开关来屏蔽它。

尽管 UPX 对大多数程序都能有不错的压缩率,但作为代价,使用 UPX 以后程序执行速度可能会有所减慢。此外,个别程序也存在不兼容 UPX 的情况,因此请你自己权衡是否值得使用。

为执行文件添加版本信息

上述大多数命令行选项都是相当直观的,相信读者参考脚本的例子就能看懂,不需要多作解释。但有一个选项有点复杂,值得拿出来说一下,那就是 --version-file

在 Windows 下,为应用程序添加版本信息是一种专业的表现,并且对软件的排错和更新也可能会有所帮助。但版本信息是一个复杂的结构————技术性的介绍可参考MSDN(https://msdn.microsoft.com/en-us/library/ff468916(v=vs.85).aspx )————自己生成版本记录文件是比较困难的。PyInstaller 考虑到了这一点,因此它为你提供了一个用于提取版本记录的辅助命令:pyi_grab_version。如果你的 PyInstaller 是通过 PIP 安装的,那么该程序应该位于 Pythonxx\Scripts 子目录下,并且如果 Python 已经添加到系统 PATH 的话,你可以直接运行此命令:

pyi-grab_version

注意中划线和下划线的写法,如果找不到命令的话,请检查一下 Scripts 子目录。

这里作为例子,我们直接从系统程序里“偷”一个版本信息过来:

pyi-grab_version c:\windows\notepad.exe version.txt

然后打开生成的 version.txt, 会看到类似下面的内容:

# UTF-8
VSVersionInfo(
  ffi=FixedFileInfo(
    # filevers and prodvers should be always a tuple with four items: (1, 2, 3, 4)
    # Set not needed items to zero 0.
    filevers=(10, 0, 17134, 1),
    prodvers=(10, 0, 17134, 1),
  ...
  kids=[
    StringFileInfo(
      [
      StringTable(
        u'040904B0',
        [StringStruct(u'CompanyName', u'Microsoft Corporation'),
        StringStruct(u'FileDescription', u'Notepad'),
        StringStruct(u'FileVersion', u'10.0.17134.1 (WinBuild.160101.0800)'),
        StringStruct(u'InternalName', u'Notepad'),
        StringStruct(u'LegalCopyright', u'© Microsoft Corporation. All rights reserved.'),
        StringStruct(u'OriginalFilename', u'NOTEPAD.EXE'),
        StringStruct(u'ProductName', u'Microsoft® Windows® Operating System'),
        StringStruct(u'ProductVersion', u'10.0.17134.1')])
      ]), 
    VarFileInfo([VarStruct(u'Translation', [1033, 1200])])
  ]
)

文件略长,这里只列出重要的部分,其结构还是很清楚的。通常,我们需要修改的是其中的版本信息和一些辅助性的描述。将文中内容修改如下:

# UTF-8
VSVersionInfo(
  ffi=FixedFileInfo(
    filevers=(1, 0, 1, 1),
    prodvers=(1, 0, 1, 1),
    ...
    ),
  kids=[
    StringFileInfo(
      [
      StringTable(
        u'040904B0',
        [StringStruct(u'CompanyName', u'Sample Corp'),
        StringStruct(u'FileDescription', u'PyInstaller application'),
        StringStruct(u'FileVersion', u'1.0.0.1'),
        StringStruct(u'InternalName', u'PyInstaller application'),
        StringStruct(u'LegalCopyright', u'Sample Corp.'),
        StringStruct(u'OriginalFilename', u'main.exe'),
        StringStruct(u'ProductName', u'PyInstaller application'),
        StringStruct(u'ProductVersion', u'1.0.0.1')])
      ]), 
    VarFileInfo([VarStruct(u'Translation', [1033, 1200])])
  ]
)

然后编译程序。从资源管理器找到发布目录下的文件(本例中应为 dist/main/main.exe),右键查看属性:

.EXE 版本信息

可见版本信息已经成功添加到 .EXE 文件中了。

在下一篇文章中,我们将介绍什么是单文件/单目录模式,以及它们之间的区别。

PyInstaller 系列索引

添加评论

评论须知:
  • 评论内容只支持纯文本格式;
  • 评论须经站长审核通过后才会发表;
  • 以下内容一概删除:灌水、广告、与主题无关、不文明,以及违法内容。
  • 若对评论处理有异议,请发邮件给站长(shuhari@outlook.com)。

评论