如何使用 Pyinstaller 编译打包 Python 项目生成 exe 可执行文件（2023 年最新详细教程）

pyinstaller 概述

PyInstaller 是一个将 Python 程序转换为独立可执行文件的工具。它能够在 Windows、Linux、Mac OS X、AIX 和 Solaris 等系统上运行。相较于其他类似的工具 PyInstaller 主要优点

1. PyInstaller 与任何 Python 版本兼容，从 2.3 版本开始支持。 2. PyInstaller 通过透明压缩功能，使生成的可执行文件更小。 3. PyInstaller 是完全跨平台的，可以在各种操作系统上运行。 4. PyInstaller 利用操作系统的支持来加载动态库，从而确保了完全的兼容性。

• 1
• 2
• 3
• 4

通过使用 PyInstaller，你可以将 Python 程序转换为单个可执行文件，从而方便地在没有 Python 解释器的机器上运行。这样做可以简化程序的分发，避免用户安装 Python 解释器的麻烦。

PyInstaller 官网：https://www.pyinstaller.org

在这里，你可以找到最新版本的 PyInstaller 下载包，以及详细的文档和用例供开发者学习和使用。

下载安装 pyinstaller

方案一：通过 pip 快速安装（PyPI 清华源镜像仓库）

通过 pip 包管理工具进行快速安装

pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple/

• 1

若本地已经安装了旧版的 pyinstaller 进行更新 pyinstaller 工具

pip install -U pyinstaller

• 1

方案二：通过 git clone 安装

git clone 项目包

Administrator@DESKTOP-AIMG6N1 MINGW64 ~/Desktop/热氧细胞/env (master) $ git clone https://github.com/pyinstaller/pyinstaller Cloning into 'pyinstaller'... remote: Enumerating objects: 60820, done. remote: Counting objects: 100% (2468/2468), done. remote: Compressing objects: 100% (1021/1021), done. remote: Total 60820 (delta 1705), reused 1893 (delta 1433), pack-reused 58352 Receiving objects: 100% (60820/60820), 56.98 MiB | 839.00 KiB/s, done. Resolving deltas: 100% (45134/45134), done.

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

cd 项目包目录

Administrator@DESKTOP-AIMG6N1 MINGW64 ~/Desktop/热氧细胞/env (master) $ cd pyinstaller

• 1
• 2

开始安装

Administrator@DESKTOP-AIMG6N1 MINGW64 ~/Desktop/热氧细胞/env/pyinstaller (develop) $ pip install .

• 1
• 2

查看 pyinstaller 版本信息（安装成功）

C:\Users\Administrator>pyinstaller --version 5.13.2

• 1
• 2

pyinstaller cmd 命令

pyinstaller 构建一个捆绑的应用程序的主命令 pyi-makespec 创建一个 spec 配置文件 pyi-archive_viewer 检查捆绑的应用程序 pyi-bindepend 显示可执行文件的依赖关系 pyi-grab_version 从 Windows 可执行文件中提取版本资源 pyi-set_version 将先前提取的版本资源应用到现有的 Windows 可执行文件中

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11

pyi-grab_version 说明

例如我们电脑上安装了 腾讯 QQ 应用，我们可以通过桌面的快捷方式右击查看 腾讯 QQ 应用的 安装目录 具体位置，进入所在目录，进行查看到存在 QQ.exe 应用程序，然后进行 CMD 命令操作，在当前目录进行打开控制台，然后输入 pyi-set_version QQ.exe 提取版本资源文件。

D:\Program Files\Tencent\QQ\Bin>pyi-set_version QQ.exe

• 1

当前所在目录生成 file_verison_info.txt 资源文件版本信息文件

简单打包 exe 案例

随便写个简单项目（例如生成二维码图片）

import qrcode # 创建二维码对象，输入文本内容 qr = qrcode.QRCode(version=1, box_size=10, border=5) qr.add_data('Hello, World!') qr.make(fit=True) # 保存二维码为图片文件 img = qr.make_image(fill_color="black", back_color="white") img.save('qrcode.png')

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10

在当前项目目录下开启 cmd 终端执行打包 exe 命令

pyinstaller -F -w main.py

• 1

项目目录会生成两个目录（build 和 dist），build是缓存文件，可以删除掉。dist 中就是打包的结果，在该目录下有生成的 exe 文件（如果非单个 exe 文件还会包含所依赖的库文件）

dist 文件夹是 PyInstaller 生成的打包文件的存放位置，其中包含与源程序同名的文件夹，以及可执行文件的动态链接库等。这个文件夹中的内容可以直接运行，其他人可以使用这个文件夹里的可执行文件。

build 文件夹是 PyInstaller 存储临时文件的目录，类似于 PyInstaller 的工作空间，其中包含相关的文件和日志信息。打包完成后，这个文件夹可以安全删除。

-F -W 常用命令参数介绍

-F: 只生成一个单个文件（只有一个 exe 文件） -w: 就是 exe 运行的时候不弹出那个控制台窗口（黑窗口）

• 1
• 2

pyinstaller 注意点

打包路径问题

注意：在使用 PyInstaller 打包 Python 源文件时，需要注意文件路径不能出现英文空格和英文句号（.），源文件必须是 UTF-8 编码，暂不支持其他编码类型。

pyinstaller 打包参数

PyInstaller 是一个用于将 Python 源文件（.py）打包成可执行文件的工具。在 PyInstaller 的打包过程中，可以选择相关 o p t i o n s options options 参数来实现其他预期效果。

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

• 1

常用命令参数

-F, --onefile：打包一个单个文件，产生一个文件用于部署。

-D, --onedir：打包多个文件，产生一个目录用于部署。

-K, --tk：在部署时包含 TCL / TK。

-a, --ascii：不包含编码，在支持 Unicode 的 python 版本上默认包含所有的编码。

-d, --debug：产生 debug 版本的可执行文件。

-w, --windowed, --noconsole：使用 Windows 子系统执行，当程序启动的时候不会打开命令行（只对 Windows 有效）。

-c, --nowindowed, --console：使用控制台子系统执行（默认），当程序启动的时候会打开命令行（只对 Windows 有效）。

-i, --icon=：将 file.ico 添加为可执行文件的资源，改变程序的图标（只对 Windows 系统有效）。

spec 配置打包案例

在 pyinstaller cmd 命令介绍了 pyi-makespec 命令，主要作用创建一个 spec 配置文件。PyInstaller 允许使用 spec 文件来配置打包过程。Spec 文件是一个文本文件，包含了一系列的配置选项和指令，用于指定如何打包Python程序。

pyinstaller --name=myprogram.spec myprogram.py

• 1

例如：在当前目前 生成 app.spec 配置文件

C:\Users\Administrator\Desktop\热氧细胞\pythonProject> pyi-makespec --name=app .\main.py Wrote C:\Users\Administrator\Desktop\热氧细胞\pythonProject\app.spec. Now run pyinstaller.py to build the executable.

• 1
• 2
• 3

要创建一个 spec 文件，可以使用 PyInstaller 的命令行工具，使用 --name 参数指定 spec 文件的名称，这将会生成一个名为 myprogram.spec 的 spec 文件。在 spec 文件中，可以添加各种配置选项和指令。

spec 配置选项 和 配置指令

# -*- mode: python ; coding: utf-8 -*-：指定文件的编码格式为UTF-8。

block_cipher = None：设置加密算法的密钥，如果不需要加密，则可以设置为 None。

a = Analysis(['myprogram.py']：指定要打包的Python源文件。

pathex=['/path/to/myprogram']：指定Python源文件的路径。

binaries=[]：指定要包含的二进制文件。

datas=[]：指定要包含的数据文件。

hiddenimports=[]：指定要包含的隐藏导入模块。

hookspath=[]：指定要搜索的钩子路径。

runtime_hooks=[]：指定要运行的运行时钩子。

excludes=[]：指定要排除的模块或包。

win_no_prefer_redirects=False：指定 Windows 下是否禁用重定向。

win_private_assemblies=False：指定 Windows 下是否使用私有程序集。

cipher=block_cipher：指定加密算法和密钥。

noarchive=False)：指定是否禁用归档。

在 spec 文件中，还可以使用 Analysis、PyInstaller 等类来定义打包过程的各种操作和选项。例如，可以使用 Analysis 类来指定要打包的 Python 源文件、二进制文件、数据文件等，使用 PyInstaller 类来指定生成的可执行文件的名称、版本、图标等。

通过编辑 spec 文件，可以自定义 PyInstaller 的打包过程，以满足特定的需求和要求。

编译打包生成 exe

如果你的 .spec 文件名为 myprogram.spec，可以通过以下命令生成 .exe 文件：

pyinstaller myprogram.spec

• 1

这将会生成一个名为 myprogram.exe 的可执行文件，在 dist 文件夹中。注意，这个命令需要在你的 .spec 文件所在的目录下运行。

新版本常见问题

C:\Users\Administrator\Desktop\热氧细胞\pythonProject> pyinstaller -F -w .\app.spec 298 INFO: PyInstaller: 5.13.2 299 INFO: Python: 3.8.5 299 INFO: Platform: Windows-10-10.0.22621-SP0 option(s) not allowed: --onedir/--onefile --console/--nowindowed/--windowed/--noconsole makespec options not valid when a .spec file is given

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8

就是说在 .spec 配置文件存在的适合，不能添加 cmd 打包参数，但是在 Pyinstaller 旧版本是可以执行的，那么新版本怎么办呢？

解决方案：在生成 .spec 配置文件的时候就添加打包参数即可。

PS C:\Users\Administrator\Desktop\热氧细胞\pythonProject> pyi-makespec --name=app -F -w .\main.py Wrote C:\Users\Administrator\Desktop\热氧细胞\pythonProject\app.spec. Now run pyinstaller.py to build the executable.

• 1
• 2
• 3

spec 配置详细介绍

script Python 脚本 配置

['hello.py']

• 1

main 文件入口，或者你执行文件的时候要执行多个 python 文件，那就写几个，比如 pyinstaller hello.py hello2.py，会依次去执行。

pathex 自定义库路径 配置

pathex=[ 'D:\\Company\\project\\untitled', 'D:\\Company' ],

• 1
• 2
• 3
• 4

意思是项目需要从什么地方导入自定义库。

# hello.py文件 from mypath.util import module1 # 从 D:\\Company\\project\\untitled 找到 mypath 文件夹下面的 util 下面的 module1 from util.module2 import * # 从 D:\\Company 目录下的 util 找到 module2

• 1
• 2
• 3

datas 资源包 配置

项目需要用到什么数据，比如图片，视频等。里面格式是 tuple，第一个参数是文件路径，第二个是打包后所在的路径。下面的代码意思就是，把 image 下面的所有以 png 结尾的文件打包到 exe 所在目录下的 data/image 目录下。把 pdf 目录下的 test.pdf 文件打包到 exe 所在目录的 data/pdf 目录下。

datas=[ ('image/*.png','data/image'), ('pdf/test.pdf','data/pdf') ],

• 1
• 2
• 3
• 4

binaries 动态库 配置

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

• 1

excludes 排除包 配置

excludes=['PyQt5']

• 1

假如你用的 python 有很多库，但是你不需要用到某个，那么就把它添加到里面去，比如很多人没有用到 PyQt5、pandas 等等第三方包。