快速上手pyinstaller

---

1. PyInstaller 安装

首先安装 PyInstaller：

pip install pyinstaller

验证安装是否成功：

pyinstaller --version

---

2. 基本用法

打包单个脚本

pyinstaller your_script.py

• 生成的文件会放在 dist/your_script/ 目录下，包含可执行文件和依赖的多个文件。

打包为单个可执行文件

pyinstaller --onefile your_script.py

• --onefile 将所有依赖和代码合并为一个独立的可执行文件。

---

3. PyInstaller 常用选项

以下是常用选项的功能和用法：

1. 添加图标

pyinstaller --onefile --icon=your_icon.ico your_script.py

• **--icon**：指定 .ico 图标文件，适用于 Windows。

---

2. 隐藏终端窗口

pyinstaller --onefile --noconsole your_script.py

• **--noconsole**：适用于 GUI 程序，隐藏终端窗口（仅在 Windows 中有效）。

---

3. 指定额外依赖路径

pyinstaller --onefile --paths=/path/to/extra/modules your_script.py

• **--paths**：用于包含 Python 脚本未在标准路径下的模块或包。

---

4. 处理隐藏导入

某些模块（如动态导入的模块）可能无法被自动检测到，需要手动指定：

pyinstaller --hidden-import=module_name your_script.py

• **--hidden-import**：解决未检测的依赖模块。

---

5. 压缩可执行文件

如果可执行文件体积较大，可以使用 UPX 压缩：

1. 安装 UPX。
2. 使用以下命令：

   pyinstaller --onefile --upx-dir=/path/to/upx your_script.py

---

6. 调试模式

在打包时开启调试模式以查看详细错误信息：

pyinstaller --debug=all your_script.py

---

7. 指定工作目录

为避免污染当前目录，可以指定工作目录：

pyinstaller --workpath=/path/to/workdir your_script.py

• **--workpath**：指定临时文件的存放目录。

---

4. 打包结果文件说明

1. **dist/**：生成的可执行文件和相关资源。
2. **build/**：构建过程中产生的临时文件。
3. .spec 文件：PyInstaller 的配置文件，可手动修改以支持更复杂的需求。

---

5. 使用 .spec 文件

生成 .spec 文件

在第一次运行 PyInstaller 时会自动生成 .spec 文件：

pyinstaller your_script.py

或手动创建：

pyinstaller --onefile --icon=your_icon.ico your_script.py

编辑 .spec 文件

你可以修改 .spec 文件来配置：

1. 数据文件（如图片、配置文件）：

   datas=[('path/to/datafile', 'destination_folder')]

2. 隐藏导入：

   hiddenimports=['module1', 'module2']

使用 .spec 文件重新打包

pyinstaller your_script.spec

---

6. 示例应用场景

简单脚本打包

假设有一个脚本 hello.py：

print("Hello, PyInstaller!")

运行以下命令：

pyinstaller --onefile hello.py

生成的可执行文件位于 dist/hello.exe。

---

打包 GUI 程序

对于 Tkinter 或 PyQt5 程序，示例脚本 gui_app.py：

from tkinter import Tk, Label

root = Tk()
Label(root, text="Hello, GUI!").pack()
root.mainloop()

运行命令：

pyinstaller --onefile --noconsole --icon=app_icon.ico gui_app.py

---

包含数据文件

如果脚本依赖额外的数据文件：

# example.py
import os

path = os.path.join(os.path.dirname(__file__), 'config.txt')
with open(path) as f:
    print(f.read())

命令：

pyinstaller --onefile --add-data "config.txt;." example.py

• **--add-data**：格式为 文件路径;目标目录。

---

7. 常见问题与解决

1. 运行时缺失模块

   • 检查日志，使用 --hidden-import 添加缺失模块。

2. 文件过大

   • 启用 UPX 压缩。
   • 检查是否有多余的依赖包。

3. 路径问题

   • 使用 sys._MEIPASS 获取运行时的临时路径：

     import sys, os
     path = os.path.join(sys._MEIPASS, 'config.txt')

---

8. 完整命令模板

综合多个参数的完整示例：

pyinstaller --onefile --noconsole --icon=app_icon.ico --add-data "config.txt;." --hidden-import=pkg_resources.py2_warn --debug=all gui_app.py

---