PyInstaller 手册

1 快速开始

确保已安装要求，然后从 PyPI 安装 PyInstaller：

pip3.8 install -U pyinstaller

验证安装

在所有平台上，该命令pyinstaller现在应该存在于执行路径上。要验证这一点，请输入命令：

pyinstaller --version

对于绝大多数程序，这可以通过一个简短的命令来完成，

pyinstaller myscript.py

或添加一些选项，例如作为单文件可执行文件的窗口应用程序，

pyinstaller --onefile --windowed myscript.py

2 选项

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

2.1 通用参数

参数名

描述

说明

-h

显示帮助

无

-v

显示版本号

无

–distpath

生成文件放在哪里

默认：当前目录的dist文件夹内

–workpath

生成过程中的中间文件放在哪里

默认：当前目录的build文件夹内

-y

如果dist文件夹内已经存在生成文件，则不询问用户，直接覆盖

默认：询问是否覆盖

–upx-dir UPX_DIR

指定upx工具的目录

默认：execution path

-a

不包含unicode支持

默认：尽可能支持unicode

–clean

在本次编译开始时，清空上一次编译生成的各种文件

默认：不清除

–log-level LEVEL

控制编译时pyi打印的信息

一共有6个等级，由低到高分别为TRACE DEBUG INFO(默认) WARN ERROR CRITICAL。也就是默认清空下，不打印TRACE和DEBUG信息

2.2 与生成结果有关的参数

参数名

描述

说明

-D

生成one-folder的程序（默认）

生成结果是一个目录，各种第三方依赖、资源和exe同时存储在该目录

-F

生成one-file的程序

生成结果是一个exe文件，所有的第三方依赖、资源和代码均被打包进该exe内

–specpath

指定.spec文件的存储路径

默认：当前目录

-n

生成的.exe文件和.spec的文件名

默认：用户脚本的名称，即main.py和main.spec

2.3 指定打包哪些资源、代码

参数名

描述

说明

–add-data

打包额外资源

用法：pyinstaller main.py --add-data=src;dest。windows以;分割，linux以:分割

–add-binary

打包额外的代码

用法：同–add-data。与–add-data不同的是，用binary添加的文件，pyi会分析它引用的文件并把它们一同添加进来

-p

指定额外的import路径，类似于使用PYTHONPATH

参见PYTHONPATH

–hidden-import

打包额外py库

pyi在分析过程中，有些import没有正确分析出来，运行时会报import error，这时可以使用该参数

–additional-hooks-dir

指定用户的hook目录

hook用法参见其他，系统hook在PyInstaller\hooks目录下

–runtime-hook

指定用户runtime-hook

如果设置了此参数，则runtime-hook会在运行main.py之前被运行

–exclude-module

需要排除的module

pyi会分析出很多相互关联的库，但是某些库对用户来说是没用的，可以用这个参数排除这些库，有助于减少生成文件的大小

–key

pyi会存储字节码，指定加密字节码的key

16位的字符串

2.4 生成参数

参数名

描述

说明

-d

执行生成的main.exe时，会输出pyi的一些log，有助于查错

默认：不输出pyi的log

-s

优化符号表

原文明确表示不建议在windows上使用

–noupx

强制不使用upx

默认：尽可能使用。

2.5 其他

参数名

描述

说明

–runtime-tmpdir

指定运行时的临时目录

默认：使用系统临时目录

2.6 Windows和Mac特有的参数

参数名

描述

说明

-c

显示命令行窗口

与-w相反，默认含有此参数

-w

不显示命令行窗口

编写GUI程序时使用此参数有用。

-i

为main.exe指定图标

pyinstaller -i beauty.ico main.py

2.7 Windows特有的参数

参数名

描述

说明

–version-file

添加版本信息文件

pyinstaller --version-file ver.txt

-m, --manifest

添加manifest文件

pyinstaller -m main.manifest

-r RESOURCE

向Windows可执行文件添加或更新资源

–uac-admin

创建一个Manifest，该Manifest将在应用程序启动时请求提升。

–uac-uiaccess

允许升级的应用程序使用远程桌面。

2.8 从 Python 代码运行 PyInstaller

import PyInstaller.__main__

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

相当于:
pyinstaller my_script.py --onefile --windowed

pyinstaller -Fw Calc.py

-w：不显示终端
-F：将所有的库打包成一个单独的文件
-i：可以设置图标路径，将图标放在根目录 32x32的ICO格式

3 使用范式文件

3.1 您可以使用以下命令创建规范文件：

pyi-makespec 选项 [其他脚本…]name.py

这些选项与上面记录的pyinstaller命令选项相同。此命令创建文件但不继续构建可执行文件。name.spec

您的捆绑应用程序是通过执行规范文件创建的。以下是最小的单文件夹应用程序的规范文件的简短示例：

# -*- mode: python ; coding: utf-8 -*-


block_cipher = None


a = Analysis(
    ['minimal.py'],  # 脚本名称
    pathex=["./"],   # 文件所在的路径
    binaries=[('/usr/lib/libiodbc.2.dylib', '.')],  # 添加二进制文件到打包应用中  相当于pyinstaller --add-binary '/usr/lib/libiodbc.2.dylib:.' myscript.py
    # 第一个字符串指定当前系统中的一个或多个文件。
    # 第二个指定在运行时包含文件的文件夹的名称。
    datas=[('src/README.txt', '.'), ('/mygame/sfx/*.mp3', 'sfx')],  # 添加文件到打包应用中  相当于pyinstaller --add-data 'src/README.txt:.' myscript.py  元祖字段含义跟binaries一致
    hiddenimports=[],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    [],
    exclude_binaries=True,
    name='text',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    console=True,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
)
coll = COLLECT(
    exe,
    a.binaries,
    a.zipfiles,
    a.datas,
    strip=False,
    upx=True,
    upx_exclude=[],
    name='text',
)

规范文件中的语句创建四个类的实例 Analysis，PYZ、EXE和COLLECT.

  • 一个新的类实例Analysis将脚本名称列表作为输入。它分析所有导入和其他依赖项。生成的对象（分配给a）包含名为的类成员中的依赖项列表：
  • scripts：命令行命名的python脚本；
  • pure：脚本所需的纯python模块；
  • pathex：搜索导入的路径列表（例如使用 PYTHONPATH)，包括选项给出的路径--paths 。
  • binaries：脚本需要的非python模块，包括--add-binary选项给出的名称；
  • datas：应用程序中包含的非二进制文件，包括--add-data选项给出的名称。
  • 类的一个实例PYZ是一个.pyz存档（在下面的检查存档中描述），它包含来自a.pure.
  • 的实例EXE是从分析的脚本和PYZ 存档中构建的。该对象创建可执行文件。
  • 的一个实例COLLECT从所有其他部分创建输出文件夹。

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

您修改规范文件以将附加值传递给Analysis和传递给EXE.

3.10 执行name.spec文件

pyinstaller -F name.spec，