PyInstaller打包Python脚本的使用示例
作者：Tiandaren
1. 写在前面
通常，在用 Python 编写完一个脚本后，需要将它部署并集成到一个更大的项目中。常见的集成方式有以下几种：
- 使用 PyInstaller 打包。
- 使用 Docker 打包。
- 将 Python 嵌入到 C++ 代码中，并封装成类。
- 将 Python 代码转换为 C++ 代码。
本文介绍其中一种方式——使用 PyInstaller 打包。通过 PyInstaller，可以将 Python 脚本打包成 .exe 文件（适用于 Windows）或适用于 macOS 和 Linux 的可执行文件，用户无需安装 Python 或任何相关依赖，便能直接运行程序。
主要优势：
- 将 Python 脚本打包成独立可执行文件，方便分发和运行。
- 支持单文件打包、图标定制、以及额外文件的捆绑。
- 可选隐藏控制台窗口，适合图形化应用（GUI）程序。
适用场景：
- 发布桌面工具或命令行程序。
- 让没有 Python 环境的用户也能使用你的工具。
- 分享自包含的 Python 项目，确保目标机器能够顺利运行。
2. 打包指令解析与参数详解
| 参数名 | 描述 | 示例 | 类型 | 必须 | 默认值 |
|---|---|---|---|---|---|
| --onefile | 将所有依赖文件打包为单个可执行文件。 | pyinstaller --onefile example.py | bool | 否 | False |
| --noconsole | 隐藏控制台窗口（适用于 GUI 应用）。 | pyinstaller --noconsole gui_app.py | bool | 否 | False |
| --name | 指定生成的可执行文件名称。 | pyinstaller --name=my_app example.py | str | 否 | 源文件名（无扩展） |
| --icon | 设置可执行文件的图标（需提供 .ico 文件）。 | pyinstaller --icon=app_icon.ico example.py | str | 否 | None |
| --add-data | 捆绑额外文件（如配置文件、静态资源等）。 | pyinstaller --add-data "config.yaml;." example.py | str | 否 | None |
| --clean | 清理之前的构建缓存，强制重新打包。 | pyinstaller --clean example.py | bool | 否 | False |
| --hidden-import | 手动添加隐藏的依赖模块（通常是自动检测遗漏的依赖）。 | pyinstaller --hidden-import=requests example.py | list | 否 | 自动检测 |
3. 基础步骤
1. 安装 PyInstaller
在终端（或命令行）中运行以下命令，安装 PyInstaller：
pip install pyinstaller
2. 使用基础命令进行打包
假设你有一个 Python 脚本 example_script.py，使用下面的命令将其打包为一个独立的可执行文件：
pyinstaller --onefile example_script.py
- 该命令会将所有依赖项和代码打包成一个单一的
.exe文件。 - 打包后，可以在
dist目录下找到生成的可执行文件。
4. 常见的用法示例
示例 1：基础打包
将 example_script.py 打包为一个单文件可执行程序：
pyinstaller --onefile example_script.py
示例 2：自定义名称和图标
将输出文件命名为 my_program.exe，并指定图标文件为 app_icon.ico：
pyinstaller --onefile --name=my_program --icon=app_icon.ico example_script.py
示例 3：捆绑额外文件
将配置文件 config.yaml 一起捆绑进可执行文件：
pyinstaller --onefile --add-data "config.yaml;." example_script.py
注意：在 Windows 系统中，路径分隔符用分号 ;，而在 macOS/Linux 中使用冒号 :。
示例 4：解决缺失依赖问题
如果在运行时遇到某个模块丢失的错误，可以通过 --hidden-import 指定手动引入依赖：
pyinstaller --onefile --hidden-import=requests example_script.py
示例 5：隐藏控制台窗口
适用于图形界面（GUI）应用程序，运行时隐藏控制台窗口：
pyinstaller --onefile --noconsole gui_app.py
5. 注意事项（路径）
路径问题：使用
--add-data时，不同操作系统的路径分隔符需特别注意。- Windows：
"source;destination" - macOS/Linux：
"source:destination"
- Windows：
文件路径问题：在代码中访问本地文件时，使用相对路径获取的文件可能会在打包后无法找到。此时，建议使用以下方式获取正确的文件路径：
BASE_DIR = os.path.dirname(os.path.realpath(sys.argv[0]))
6. 错误处理和日志记录
在打包的 Python 应用中，为了方便调试，可以加入错误处理代码，将错误信息记录到文件中，帮助定位问题。
try:
# 代码逻辑
pass
except Exception as e:
print("An error occurred:", e)
with open("error_log.txt", "w") as f:
f.write(str(e))
如果可执行文件出现问题，能够在 error_log.txt 中查看详细的错误信息。
例如，
这就是一个文件路径错误的报错，原因在于生成的可执行文件是在 dist 目录下，但是文件路径是相对路径，在 ../ 上，知道问题就可以解决了。否则，有时候连报错都不知道在哪。
另外，如果想要更加优雅地打包python，建议配合以下教程食用：
Python 参数配置使用 XML 文件的教程：轻松管理你的项目配置
到此这篇关于PyInstaller打包Python脚本的使用示例的文章就介绍到这了,更多相关PyInstaller打包Python脚本内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！