使用pyinstaller将Python文件打包成exe

本文介绍如何使用pyinstaller将.py文件打包成exe。

1 环境准备

conda：

conda install pyinstaller

pip:

pip install pyinstaller

检查是否安装成功：

pyinstaller --version

2 打包

基本使用方法

1. 打包 Python 脚本

   pyinstaller your_script.py

   运行后将在当前目录生成以下文件和文件夹：

   • dist/：生成的可执行文件所在目录。
   • build/：临时文件夹，包含打包时的构建文件。
   • your_script.spec：PyInstaller 的配置文件。

   打包的可执行文件位于 dist/your_script/ 文件夹中。

2. 生成单文件可执行文件

   pyinstaller -F your_script.py

   生成的单文件可执行文件位于 dist/ 文件夹中。

   指定打包路径：

   pyinstaller -F --distpath ./output script.py

3. 无控制台窗口
   如果你的程序是 GUI 应用（如使用 tkinter 或 PyQt），不需要显示控制台窗口：

   pyinstaller -F -w your_script.py

   -w（或 --noconsole）会隐藏控制台窗口。

完成打包后

.exe文件默认放在dist/文件夹下：

project/
├── script.py
├── build/                 # 打包时的临时文件夹
├── dist/                  # 生成的可执行文件所在目录
│   └── script.exe
└── script.spec            # PyInstaller 的配置文件

可以通过修改配置文件中COLLECT函数，添加或者修改distpath参数，修改文件打包位置。

1. 单文件模式 (-F) 的可执行文件
   移动 .exe 文件单文件模式 (-F) 的可执行文件
   直接移动 .exe 文件到任何位置都可以运行，因为所有的依赖都已经打包进去了。例如：

dist/
└── script.exe -> 移动到任意位置后仍可运行

2. 文件夹模式的可执行文件
   如果使用的是文件夹模式（–onedir 或默认模式），.exe 文件需要和生成的其他依赖文件保持在一起才能运行。例如：

dist/script/
├── script.exe
├── library.zip
├── ...（其他依赖文件）

在这种情况下，移动 .exe 文件时需要整个文件夹一起移动。

---

常用参数详解

以下是 PyInstaller 常用参数及其功能：

参数	功能
基本参数
-F, --onefile	将所有文件打包成一个独立的可执行文件。
-D, --onedir	（默认）将生成的文件放在一个文件夹中，包括依赖文件和可执行文件。
-w, --noconsole	隐藏控制台窗口（适用于 GUI 应用）。
-c, --console	默认显示控制台窗口（适用于 CLI 应用）。
--name=NAME	指定生成的可执行文件名称（默认为脚本名）。
依赖处理
--hidden-import=MODULE	手动指定未被自动检测到的模块。
--exclude-module=MODULE	从打包中排除某些模块。
--add-data=SRC;DEST	将额外的数据文件（如图片、配置文件等）打包到指定目录中。使用分号分隔源文件和目标路径。
优化与调试
--clean	清除旧的构建文件（如 build/ 目录）。
--log-level=LEVEL	设置日志级别（可选值：DEBUG、INFO、WARN、ERROR）。
运行环境
--icon=ICON_PATH	指定可执行文件的图标（支持 .ico 格式）。
--key=KEY	对 Python 字节码加密时使用的密钥。
--debug	生成带调试信息的可执行文件。

---

高级用法示例

1. 添加资源文件（图片、配置文件等）
   将图片或其他资源文件打包到可执行文件中：

   pyinstaller -F --add-data "config.json;." --add-data "images/icon.png;images" your_script.py

   • config.json;. 表示将 config.json 放到可执行文件的根目录。
   • images/icon.png;images 表示将 icon.png 放到 images/ 文件夹中。

2. 指定图标
   为可执行文件指定图标：

   pyinstaller -F --icon=icon.ico your_script.py

3. 处理隐藏依赖
   某些动态导入的模块可能不会被 PyInstaller 自动检测到，需要显式指定：

   pyinstaller -F --hidden-import=module_name your_script.py

4. 加密 Python 字节码
   使用加密密钥保护 Python 源码：

   pyinstaller -F --key=my_secret_key your_script.py

5. 生成调试版本
   为调试生成的可执行文件：

   pyinstaller -F --debug your_script.py

---

常见问题与解决

1. 依赖模块未正确打包

   • 使用 --hidden-import 显式添加依赖模块。
   • 使用 pip show module_name 查看依赖路径，确保依赖已安装。

2. 路径问题

   • 动态加载的文件可能需要 os.path 获取运行时路径。使用以下代码适配 PyInstaller 的运行路径：

     import os
     import sys
     
     def resource_path(relative_path):
         if getattr(sys, 'frozen', False):  # 如果是打包后的 exe
             base_path = sys._MEIPASS
         else:
             base_path = os.path.abspath(".")
         return os.path.join(base_path, relative_path)

3. 文件过大

   • 使用 --onedir 打包到文件夹形式，减少启动时间。
   • 删除不必要的模块或依赖，使用 --exclude-module 参数。

4. exe在用户输入后程序闪退

   • 在程序末尾添加input("\n按回车键退出程序...")，即使运行结束也会等待用户按回车键后退出。
   • 使用try-except 和 log捕获运行错误，记录到日志文件中

---

参考命令总结

用途	命令示例
打包单文件	pyinstaller -F script.py
打包带图标的单文件	pyinstaller -F --icon=icon.ico script.py
打包隐藏控制台窗口	pyinstaller -F -w script.py
添加资源文件	pyinstaller -F --add-data "data.json;." script.py
加入未检测到的模块	pyinstaller -F --hidden-import=module_name script.py
生成调试版本	pyinstaller -F --debug script.py

PyInstaller 是功能强大的工具，但需要根据具体的需求和环境进行调整和优化。掌握这些参数和技巧可以更高效地创建可执行文件。

本文参考GPT和百度