pyinstaller打包python项目

一、引言

在日常工作中，基本都是直接执行python脚本，但最近有个项目，需要提供给外部使用，而使用者又完全没有编程基础，不太可能自己安装python，安装各种依赖，所以将python项目打包为exe程序就显得尤为必要。

二、打包工具选型

在Python项目中，常见的打包工具有以下几种：

1. PyInstaller

优点：

能够将Python程序及其依赖库打包成一个独立的可执行文件（Windows、Linux、macOS），无需目标环境安装Python解释器或额外的库。

支持多种类型的可执行文件输出，包括单文件和多文件形式。

可以通过隐藏源代码实现一定程度上的保护。

缺点：

对于大型复杂项目，生成的可执行文件可能会非常大。

针对某些动态加载库或特定系统调用的情况支持不够完美，可能需要手动编写.spec配置文件进行更精细的控制。

对于更新频繁的应用，每次更新都需要重新打包和分发。

2. cx_Freeze

优点：

类似于PyInstaller，也可以将Python程序打包为跨平台的可执行文件。

它允许开发者自定义包含哪些模块，提供了灵活的配置选项。

缺点：

设置相对复杂，尤其是处理复杂的第三方库依赖时。

更新版本后的兼容性问题有时会比PyInstaller更多。

3. Nuitka

优点：

Nuitka是另一种可以将Python编译为独立可执行文件的工具，但其工作原理与PyInstaller不同，它尝试直接将Python代码转换为C++代码再编译为本地机器码，理论上可以获得更好的性能。

提供了更多的优化选项和更为细致的控制。

缺点：

打包过程可能较慢，特别是对于大型项目。

兼容性和稳定性相较于成熟的PyInstaller可能有所不足，部分库可能无法良好支持。

4. py2exe (仅适用于Windows)

优点：

专门为Windows设计，可以将Python程序打包为Windows上的.exe文件。

缺点：

不支持其他操作系统，应用场景有限。

5. pip & Wheel

优点：

pip是Python的标准包管理器，结合wheel格式，可以方便地打包和分发纯Python库，不涉及GUI应用。

在Python环境中易于安装和升级。

缺点：

不能直接用于创建独立可执行文件，主要用于发布和安装纯Python模块到已安装有Python解释器的环境中。

6. setuptools & distutils

优点：

这两个模块是Python标准库的一部分，用于构建和分发Python包，提供了一种标准化的方式来组织和打包代码以便在各种环境下安装。

缺点：

同样不适合生成独立运行的可执行文件，主要面向开发人员分发库和模块，而非终端用户。

工具选择

根据项目的实际需求，例如是否需要跨平台支持、是否要求独立运行、是否关注性能等，可以选择最合适的打包工具。

对于大部分桌面应用或者希望在没有Python环境的目标机器上运行的项目，PyInstaller和cx_Freeze是较为常用的选择。

而对于纯Python库的分发，则更适合使用pip配合setuptools或wheel。

我们的使用场景是需要能够独立运行，对性能要求不是太严苛，最好能支持跨平台，再综合考虑成熟度和可靠性，最终选择pyinstaller

三、pyinstaller打包

1. 安装pyinstaller

pip install -U pyinstaller

注意：建议最后在虚拟环境下安装pyinstaller，再执行打包操作，这样会只打包该项目所需要的依赖。否则会将真实环境中很多不需要的依赖也打包进去，造成打包后的程序过大

2. 定位到你的Python源代码文件

使用cd命令切换到包含主Python脚本（例如：main.py）的目录。

3. 执行打包指令

PyInstaller打包Python应用时，可以使用一系列参数来控制打包过程。以下是一些常用的PyInstaller命令行参数说明：

1. 基本打包指令：

pyinstaller your_script.py

这是最基本的打包命令，它会根据your_script.py生成一个可执行文件和依赖文件目录

2. 输出类型选项

1. 打包为单个文件 好处是不用担心程序被篡改，同时避免代码被破解 缺点是每次启动等于要临时解压缩一次，性能会受影响

# 将所有内容打包到单个可执行文件中（推荐用于大多数情况）
-F, --onefile

1. 打包为文件夹 将所有内容打包到到一个目录下，包含可执行文件及依赖库，资源文件等（推荐用于大多数情况）

-D, --onedir：生成一个包含可执行文件以及依赖库的目录结构（适用于需要查看或编辑内部文件的情况）。

3. 图标设置

--icon=icon.ico 或 -i icon.ico：为生成的可执行文件指定一个图标文件。

4. 运行环境相关：

1. 控制台窗口显示 -w, --windowed 或 --noconsole：不显示控制台窗口（适用于GUI应用）。
2. 手动添加隐藏导入模块 --hidden-import module_name：手动添加一个隐藏导入模块，以防PyInstaller在分析过程中遗漏。

5. 数据文件包含

--add-data 将数据文件添加到打包后的程序中，并指定其在打包后的位置。

数据文件路径与打包后路径以:分隔

可以有0个或多个--add-data

--add-data path/to/data:dest/path
--add-data path/to/*.ini:.

6. 代码优化

-O, --optimize 或 --strip：对生成的代码进行优化和剥离未使用的符号，减小程序体积。

7. 指定解释器路径：

--pythonpath=path：添加额外的搜索路径给Python解释器。

8. 自定义.spec文件：

pyinstaller your_script.spec：如果你有一个.spec配置文件，可以直接通过它来编译项目。

根据.spec配置文件打包属于相对比较高级的用法，一般用不上。

9. 排除不需要的模块

--exclude-module module_name：从打包中排除指定的模块。

10. 运行时挂钩

--runtime-hook RUNTIME_HOOKS：指定运行时挂钩脚本，在主程序运行前被调用。

请根据实际需求组合这些参数。完整且详细的参数列表可以通过运行 pyinstaller --help 查看。

四、打包踩坑记录

1. 打包后运行闪退，无法查看错误信息

解决措施: 在cmd窗口中执行打包后的程序，可以查看到对应报错信息

2. 打包时报错PermissionError: WinError 32 另一个程序正在使用此文件，进程无法访问。

解决措施: 关闭其他正在使用打包目录中某个文件的程序

3. 打包后运行程序报错找不到资源文件

解决措施： 代码中的资源文件路径尽量使用相对路径

4.打包后执行exe报错Error loading Python DLL

Error loading Python DLL 'F:\xxxxxx\python311.dll'. LoadLibrary: 找不到指定的模块。

这个错误提示表明在运行使用PyInstaller打包后的exe文件时，系统未能找到Python的动态链接库（DLL）文件——python311.dll。这通常是由于以下原因导致：

1. Python环境不匹配： 打包时使用的Python版本与目标机器上的Python版本不一致，或者目标机器上根本未安装该版本的Python。你需要确保目标机器上有与打包时相同的Python DLL。
2. 依赖库缺失： PyInstaller虽然会尝试将所有必要的依赖打包到生成的可执行文件中，但有时可能会遗漏某些动态链接库。检查并确认所有必需的Python组件和第三方库是否已正确包含在最终发行版中。
3. 路径问题： 如果你在打包过程中没有正确配置或使用了--onefile选项，那么可能需要将Python DLL所在目录添加到系统的PATH环境变量中，或者确保所需的dll文件与exe文件位于同一目录下。
4. 打包参数不足： 确保在打包时使用了正确的参数来确保所有依赖都被包含在内。例如，可以尝试使用如下命令进行更全面的打包：

pyinstaller --onedir --add-binary "path_to_python311.dll;." --paths "path_to_python_libs" main.py