PyInstaller 使用指南

概述

PyInstaller 是将 Python 程序打包为独立可执行文件的工具，支持跨平台生成 .exe、.app 等文件。它通过将程序代码、依赖库及资源文件整合，使目标系统无需安装 Python 环境即可运行程序。

核心功能

• 跨平台支持：生成适用于 Windows、Linux 和 macOS 的可执行文件。
• 依赖管理：自动打包标准库和第三方库，支持手动添加数据文件或二进制文件。
• 定制化配置：通过命令行参数或 .spec 文件精细控制打包过程。

使用方法

1. 安装 PyInstaller

通过 pip 安装 PyInstaller：

pip install pyinstaller

2. 基础打包命令

默认打包会生成 dist/ 目录，包含可执行文件和依赖：

pyinstaller your_script.py

3. 常用参数说明

• --onefile：将所有内容打包为单个可执行文件。
• --windowed / --noconsole：隐藏命令行窗口（适用于 GUI 程序）。
• --add-data：添加数据文件（路径格式：源路径:目标路径，Windows 用分号 ;，Linux/macOS 用冒号 :）。
• --hidden-import：显式指定未被自动检测的依赖模块。
• --icon：为可执行文件设置图标（如 --icon=my_icon.ico）。
• --clean：清理缓存文件，避免旧版本干扰。

4. 使用 .spec 文件

.spec 文件是 PyInstaller 的配置模板，可手动编辑以定制打包逻辑：

1. 生成 .spec 文件：

   pyinstaller your_script.py
   

2. 修改 Analysis 部分，添加依赖、数据文件或二进制文件：

   a = Analysis(
       ['your_script.py'],
       binaries=[('/path/to/libexample.so', '.')],
       datas=[('config.json', '.'), ('images:images')],
       hiddenimports=['module1', 'module2']
   )
   

3. 通过 .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. 依赖缺失：使用 --hidden-import 显式指定未被检测到的模块。
2. 数据文件路径错误：确保 --add-data 的路径格式与操作系统匹配（Windows 用 ;，Linux/macOS 用 :）。
3. 打包失败：检查 PyInstaller 输出日志，排查权限问题或文件路径错误。
4. 文件体积过大：使用 --strip（Linux）或 --onefile 优化体积。
5. GUI 程序显示控制台：确认是否添加了 --windowed 或 --noconsole 参数。

目录结构说明

打包后生成的目录包含：

• dist/：最终可执行文件。
• build/：临时构建文件。
• .spec：配置文件，用于后续修改和重新打包。

总结

PyInstaller 提供了简单直观的命令行接口和灵活的配置选项，适用于大多数 Python 程序的打包需求。通过 .spec 文件可实现更精细的控制，但需注意路径格式和依赖管理。对于复杂场景，建议结合官方文档进一步调整配置。