如何使用 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 利用操作系统的支持来加载动态库，从而确保了完全的兼容性。

通过使用 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/

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

pip install -U pyinstaller

方案二：通过 git clone 安装

git clone 项目包

Administrator@DESKTOP-AIMG6N1 MINGW64 ~/Desktop/热氧细胞/env (master)$ git clone https://github.com/pyinstaller/pyinstallerCloning 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 58352Receiving objects: 100% (60820/60820), 56.98 MiB | 839.00 KiB/s, done.Resolving deltas: 100% (45134/45134), done.

cd 项目包目录

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

开始安装

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

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

C:\Users\Administrator>pyinstaller --version5.13.2

pyinstaller cmd 命令

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

pyi-grab_version 说明

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

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

当前所在目录生成 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')

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

pyinstaller -F -w main.py

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

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

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

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

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

pyinstaller 注意点

打包路径问题

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

pyinstaller 打包参数

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

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

常用命令参数

-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

例如：在当前目前 生成 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.

要创建一个 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

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

新版本常见问题

C:\Users\Administrator\Desktop\热氧细胞\pythonProject> pyinstaller -F -w .\app.spec298 INFO: PyInstaller: 5.13.2299 INFO: Python: 3.8.5299 INFO: Platform: Windows-10-10.0.22621-SP0option(s) not allowed:--onedir/--onefile--console/--nowindowed/--windowed/--noconsolemakespec options not valid when a .spec file is given

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

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

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

spec 配置详细介绍

script Python 脚本 配置

['hello.py']

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

pathex 自定义库路径 配置

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

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

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

datas 资源包 配置

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

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

binaries 动态库 配置

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

excludes 排除包 配置

excludes=['PyQt5']

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