Python PyInstaller打包方法介绍

为了将开发好的Python工具交付给其他人使用，除了在目标电脑部署Python编译环境以外，我们还可以将它打包成可执行文件，这样目标电脑不需要安装Python环境就可以运行。将Python程序打包成可执行文件的方法有多种，比如Nuitka、PyInstaller等，本文介绍比较常用的打包工具PyInstaller的使用方法。

0 环境说明

本文所使用的Windows系统为Windows11，安装的Python版本为3.10.11。

Linux系统发行版本为centos7，安装的Python版本为3.10.11。

Python环境安装方法可参考Python环境配置以及包管理方法详细介绍 。

1 PyInstaller安装

PyInstaller github仓库地址为：https://github.com/pyinstaller/pyinstaller

安装好Python环境后(我使用的Python版本为3.10.11)，使用pip命令安装即可：

pip install pyinstaller

2 PyInstaller常用参数

下面是pyinstaller的常用参数：

• --name : 指定可执行文件名称。
• --specpath: 指定spec文件的生成目录，默认为当前目录。
• -F, --onefile: 将整个应用程序打包到单个可执行文件中。
• -D, --onedir: 生成一个目录，包含多个文件。
• --add-data 、 --add-binary： 在构建中插入额外的数据或二进制文件，可用于绑定配置文件、示例或其他非代码数据。
• --exclude-module: 排除某些模块。
• -d, --debug: 提供debug输出。
• -w, --windowed, --noconsole: 关闭控制台窗口(仅对Windows有效)。
• -c, --nowindowed, --console: 使用命令行窗口(仅对Windows有效)。
• -i: 设置应用图标。

在项目根目录，打开命令行窗口执行命令：pyinstaller 项目入口函数 即可进行打包，主要生成以下三个内容：

• *.spec 文件
• build/ 文件夹：用于构建可执行文件
• dist/ 文件夹：包含应用程序的所有依赖项和可执行文件

3 示例项目

本文使用pyinstaller对一个FastAPI示例项目进行打包，github地址为：

https://github.com/hiyongz/FastAPI-example

4 Windows环境打包方法

可以先使用pyi-makespec命令生成spec文件，对spec文件进行编辑，然后使用pyinstaller打包。

4.1 只生成一个exe可执行文件

在项目根目录执行如下命令，main.py为python项目入口文件，设置显示控制台：

$ pyi-makespec -F -c main.py 

执行完成后，会生成名为main.spec的文件。如果项目包括静态文件，需修改main.spec文件，在datas中设置静态文件路径，比如：

datas=[('config/config.yaml', 'config'), ('ui/main.ui', 'ui')]

执行pyinstaller命令打包：

$ pyinstaller main.spec

打包完成后，在根目录下会生成build/ 和dist/文件夹，dist/文件夹下会生成一个main.exe的文件，将main.py文件复制到dist目录下，双击main.exe文件即可运行应用：

INFO:     Started server process [20920]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

浏览器访问 http://localhost:8001/docs 即可查看接口文档。

4.2 生成多文件

使用-D参数可生成多文件，这种方式打包的文件启动效率更高，按自己需求选择即可。

$ pyi-makespec -D -c main.py

也可以直接使用pyi-makespec main.py命令生成，默认采用的是多文件模式。

4.3 设置应用图标

准备好应用icon文件，执行以下命令：

pyi-makespec -F -i logo_favicon-wechat.ico --name=main main.py

注意需要使用--name参数设置一下应用名称，执行完成后会生成名称为main.spec的文件，编辑main.spec文件后，执行pyinstaller main.spec命令打包即可。

5 Linux环境打包方法

Linux环境下pyinstaller打包方法和windows类似，使用如下命令生成单个可执行文件：

$ pyi-makespec -F main.py
$ pyinstaller main.spec

打包完成后，会在dist目录下生成名为main的可执行文件。

[root@Server dist]# ls
main  main.py
[root@Server dist]# 
[root@Server dist]# ./main 
INFO:     Started server process [9304]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

6 常见报错

6.1 Linux环境打包报错

打包时报如下错误：

PyInstaller.exceptions.PythonLibraryNotFoundError: Python library not found: libpython3.10.so, libpython3.10.so.1.0
    This means your Python installation does not come with proper shared library files.
    This usually happens due to missing development package, or unsuitable build parameters of the Python installation.

解决方案如下：

重新编译python，加入--enable-shared选项：

./configure --prefix=/usr/local/python3 --enable-shared

然后执行make && make install命令重新编译安装。

然后执行如下命令：

$ echo "/usr/local/python3/lib/" >> /etc/ld.so.conf
$ ldconfig

--THE END--