PyInstaller入门

PyInstaller 是一个常用的 Python 打包工具，可以将 Python 脚本打包成独立的可执行文件（如 .exe），无需在目标机器上安装 Python 环境。以下是详细的使用指南：

一、安装 PyInstaller

pip install pyinstaller

二、基本使用流程

1. 简单打包（单文件）

pyinstaller --onefile your_script.py

• 效果：在 dist/ 目录下生成一个单独的可执行文件（适合分发）。
• 特点：文件较大，但无需依赖其他文件。

2. 打包为目录（多文件）

pyinstaller your_script.py

• 效果：在 dist/ 目录下生成一个文件夹，包含可执行文件和依赖库。
• 特点：启动速度更快，适合调试或依赖复杂的项目。

三、常用参数

参数	作用	示例
--onefile	打包成单个可执行文件（体积大，但便于分发）。	pyinstaller --onefile main.py
--windowed	不显示命令行窗口（仅适用于 GUI 程序，如 PyQt、Tkinter）。	pyinstaller --windowed app.py
--name NAME	指定输出文件的名称。	pyinstaller --name myapp main.py
--icon ICON.ico	指定程序图标（需 .ico 格式）。	pyinstaller --icon myicon.ico main.py
--add-data	添加非 Python 文件（如图片、配置文件）。	pyinstaller --add-data "data.json;." main.py
--hidden-import	指定隐藏依赖（某些动态导入的模块不会被自动检测）。	pyinstaller --hidden-import module_name main.py
--clean	清理打包过程中的临时文件。	pyinstaller --clean main.py

四、高级用法

1. 打包带资源文件的项目

若项目依赖外部文件（如图片、配置文件），使用 --add-data 参数：

# Windows 语法
pyinstaller --add-data "images\*;images" --add-data "config.ini;." main.py# macOS/Linux 语法
pyinstaller --add-data "images/*:images" --add-data "config.ini:." main.py

• 语法说明：源路径;目标路径（Windows）或 源路径:目标路径（macOS/Linux）。
• 在代码中引用资源：

  import sys
  import osdef resource_path(relative_path):"""获取打包后的资源路径"""if hasattr(sys, '_MEIPASS'):return os.path.join(sys._MEIPASS, relative_path)return os.path.join(os.path.abspath("."), relative_path)# 使用示例
  config_path = resource_path("config.ini")
  image_path = resource_path("images/logo.png")
  

2. 创建.spec 文件（高级配置）

PyInstaller 会自动生成 .spec 文件，可手动编辑以定制打包过程：

pyinstaller --name myapp --onefile main.py  # 先执行一次生成 myapp.spec

编辑 .spec 文件（示例）：

# myapp.spec
a = Analysis(['main.py'],pathex=['/path/to/project'],binaries=[],datas=[('images/*', 'images')],  # 添加资源文件hiddenimports=['module_name'],  # 添加隐藏依赖
)
pyz = PYZ(a.pure)
exe = EXE(pyz,a.scripts,a.binaries,a.zipfiles,a.datas,name='myapp',icon='myicon.ico',  # 图标console=False,  # 不显示命令行窗口
)

然后使用 .spec 文件打包：

pyinstaller myapp.spec

五、常见问题及解决方案

1. 打包后程序无法运行：

   • 原因：缺少隐藏依赖或资源文件。
   • 解决：使用 --hidden-import 添加依赖，或检查 .spec 文件中的 datas 配置。

2. 打包文件体积过大：

   • 优化方法：

     # 1. 使用 UPX 压缩（需先安装 UPX）
     pyinstaller --onefile --upx-dir=/path/to/upx main.py# 2. 创建虚拟环境，仅安装必要依赖
     python -m venv myenv
     source myenv/bin/activate  # Windows: myenv\Scripts\activate
     pip install -r requirements.txt
     pyinstaller --onefile main.py
     

3. GUI 程序打包后一闪而过：

   • 原因：未使用 --windowed 参数，或代码中存在异常导致程序崩溃。
   • 解决：

     pyinstaller --windowed --onefile gui_app.py
     

     或在代码中添加异常捕获：

     try:main()  # 主函数
     except Exception as e:print(f"Error: {e}")input("Press Enter to exit...")  # 防止窗口关闭
     

六、示例：打包 Tkinter 程序

# 打包 Tkinter 程序（不显示命令行窗口）
pyinstaller --windowed --onefile --name myapp --icon myicon.ico main.py

七、注意事项

1. 跨平台打包：

   • 需在目标平台（如 Windows、macOS、Linux）上分别打包。
   • 不支持直接从 Windows 打包 macOS/Linux 程序。

2. 依赖版本：

   • 确保开发环境和打包环境的依赖版本一致，避免兼容性问题。

3. 动态加载模块：

   • 对于使用 importlib 等动态加载的模块，需手动添加 --hidden-import。

通过以上步骤，你可以将 Python 脚本打包为独立可执行文件，方便分发和部署。如需更复杂的配置，建议参考 PyInstaller 官方文档。