为了将开发好的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.0This 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--