使用 PyInstaller 打包 Python 程序为独立可执行文件

概述

PyInstaller 是一个将 Python 程序打包为独立可执行文件的工具，支持跨平台生成 .exe（Windows）、.app（macOS）等格式。其核心功能是将 Python 脚本、依赖库、资源文件等整合到单个文件或目录中，使目标系统无需安装 Python 环境即可运行程序。

安装与基础用法

安装 PyInstaller

通过 pip 安装 PyInstaller：

pip install pyinstaller

基础打包命令

默认情况下，PyInstaller 会将程序和依赖拆分为多个文件：

pyinstaller your_script.py

生成的可执行文件位于 dist/ 目录，打包过程中生成的临时文件存放在 build/ 目录，.spec 配置文件用于后续自定义打包。

常用命令选项

1. --onefile：生成单个可执行文件

将所有内容打包为一个文件，便于分发：

pyinstaller --onefile your_script.py

2. --windowed / --noconsole：隐藏控制台窗口

适用于 GUI 程序（如 tkinter、PyQt 应用），避免弹出命令行窗口：

pyinstaller --onefile --windowed your_script.py

3. --add-data：添加外部数据文件

• Windows：用分号 ; 分隔源路径和目标路径
• Linux/macOS：用冒号 : 分隔源路径和目标路径

示例：添加配置文件和图片目录：

pyinstaller --onefile \
  --add-data "config.json;." \
  --add-data "images:images" \
  your_script.py

4. --hidden-import：显式指定未被自动检测的模块

用于解决动态导入模块未被包含的问题：

pyinstaller --onefile \
  --hidden-import=module1 \
  --hidden-import=module2 \
  your_script.py

5. --add-binary：添加非 Python 二进制文件

如 .so（Linux）、.dll（Windows）等：

pyinstaller --onefile \
  --add-binary "/path/to/libexample.so:." \
  your_script.py

6. --icon：设置可执行文件图标

需提供 .ico（Windows）或 .icns（macOS）格式的图标文件：

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

7. --clean：清理缓存

清除旧的构建文件，避免版本残留问题：

pyinstaller --clean your_script.py

8. --strip（Linux 专属）：去除调试符号

减小文件体积，但可能影响调试：

pyinstaller --onefile --strip your_script.py

使用 .spec 文件精细配置

生成 .spec 文件

首次运行 PyInstaller 会自动生成配置文件：

pyinstaller your_script.py

修改 .spec 文件

编辑 your_script.spec 文件，调整以下关键参数：

a = Analysis(
    ['your_script.py'],
    pathex=['/path/to/script'],
    binaries=[('/path/to/libexample.so', '.')],  # 添加二进制文件
    datas=[('config.json', '.')],                 # 添加数据文件
    hiddenimports=['module1', 'module2']          # 添加隐藏导入
)

重新打包

修改后通过 .spec 文件重新生成：

pyinstaller your_script.spec

示例：完整打包命令

以下命令整合了多种选项：

pyinstaller --onefile \
  --icon=my_icon.ico \
  --add-data "config.json;." \
  --add-data "images:images" \
  --hidden-import=module1 \
  --hidden-import=module2 \
  your_script.py

常见问题与注意事项

1. 依赖缺失

   • 现象：运行时报错 ModuleNotFoundError
   • 解决：使用 --hidden-import 显式添加缺失模块

2. 数据文件未包含

   • 现象：程序无法读取配置文件或资源
   • 解决：检查 --add-data 的路径分隔符是否符合平台规范（; 或 :）

3. 打包错误信息分析

   • PyInstaller 会输出详细日志，注意检查路径权限、文件是否存在等问题

4. 可执行文件体积过大

   • 建议：使用 --strip（Linux）或 --onefile 压缩内容

5. GUI 程序显示控制台窗口

   • 现象：PyQt/tkinter 程序弹出命令行窗口
   • 解决：确保使用 --windowed 或 --noconsole 参数

6. 路径问题

   • 打包后的程序中，数据文件路径需以 sys._MEIPASS 为根目录访问（需在代码中处理）

打包后目录结构示例

假设脚本为 your_script.py，且添加了配置文件和图片目录：

your_project/
├── your_script.py
├── config.json
├── images/
│   ├── image1.png
│   └── image2.png
├── build/              # 构建临时文件
├── dist/               # 最终生成的可执行文件
│   └── your_script.exe # Windows 示例
├── your_script.spec    # 配置文件
└── PyInstaller-hooks/  # 自动生成的依赖分析文件

注意：若使用 --onefile，所有内容会被打包到 your_script.exe 中，dist/ 目录下仅包含该文件。