PyInstaller 工具使用文档及打包教程

PyInstaller 工具使用文档

一、工具简介

PyInstaller 是一个跨平台的 Python 打包工具，可将 Python 脚本及其依赖项打包成独立的可执行文件（如 Windows 下的 .exe、Linux 下的可执行文件、macOS 下的 .app），无需目标设备安装 Python 解释器即可运行。

二、安装方法

通过 pip 命令快速安装：

pip install pyinstaller

如需安装指定版本：

pip install pyinstaller==版本号

三、基本使用语法

pyinstaller [选项] 脚本路径

四、常用命令选项

1. 基础打包

   • 生成多文件（默认，在 dist 目录下生成依赖文件夹和可执行文件）：

     pyinstaller script.py
     

   • 生成单文件（所有依赖打包进一个 .exe）：

     pyinstaller -F script.py  # 或 --onefile
     

2. 窗口设置

   • 隐藏控制台窗口（GUI 程序常用）：

     pyinstaller -w script.py  # 或 --windowed
     

   • 强制显示控制台窗口（默认，用于调试）：

     pyinstaller -c script.py  # 或 --console
     

3. 自定义输出

   • 指定输出目录：

     pyinstaller -D 目标路径 script.py  # 或 --distpath
     

   • 清理临时文件（build 目录和 .spec 文件）：

     pyinstaller --clean script.py
     

4. 图标设置

   • 为可执行文件添加图标（Windows 用 .ico，macOS 用 .icns）：

     pyinstaller -i icon.ico script.py  # 或 --icon
     

5. 高级选项

   • 排除不必要的模块：

     pyinstaller --exclude-module 模块名 script.py
     

   • 打包额外文件（如配置文件、图片等）：

     pyinstaller --add-data "源文件路径;目标路径" script.py  # Windows 用分号分隔
     pyinstaller --add-data "源文件路径:目标路径" script.py  # Linux/macOS 用冒号分隔
     

五、打包流程说明

1. 执行打包命令后，PyInstaller 会在当前目录生成 3 个内容：

   • build/：临时文件目录（可删除）
   • dist/：最终可执行文件及依赖（需保留）
   • 脚本名.spec：打包配置文件（可编辑自定义打包规则）

2. 若需修改打包细节（如添加资源文件、设置隐藏导入等），可编辑 .spec 文件后执行：

   pyinstaller script.spec
   

六、常见问题解决

1. 打包后运行报错“缺少模块”

   • 原因：部分动态导入的模块未被自动识别。
   • 解决：通过 --hidden-import 手动指定：

     pyinstaller --hidden-import 模块名 script.py
     

2. 单文件打包后运行速度慢

   • 原因：单文件运行时需解压临时文件。
   • 建议：非必要时使用多文件模式（默认）。

3. 中文路径/文件名导致打包失败

   • 解决：确保脚本路径及文件名无中文或特殊字符。

4. 杀毒软件误报

   • 部分情况下，打包后的 .exe 可能被误判为病毒，可添加信任或使用数字签名。

七、跨平台说明

• PyInstaller 需在目标系统上打包（如在 Windows 打包 .exe，在 Linux 打包 Linux 可执行文件）。
• 若需跨系统打包，可借助虚拟机或 Docker 环境。

通过上述命令和配置，可快速将 Python 脚本打包为可分发的可执行文件，适合分享或部署到无 Python 环境的设备。

八、实战出现的问题

为什么出现cmd弹窗

使用 pyinstaller -F 打包的 exe 文件运行时出现 cmd 弹窗（命令行窗口），是因为默认打包模式会为 GUI 程序额外生成一个控制台窗口，这是 PyInstaller 的默认行为。
解决方法很简单，只需在打包时添加 --noconsole 或 -w 参数（二者等效），禁用控制台窗口即可。
修改后的打包命令：
bash
pyinstaller -F -w 代码文件路径+代码文件名
说明：
-F：生成单个可执行文件
-w（或 --noconsole）：指定程序为窗口模式（无控制台），适用于 GUI 程序（如 tkinter 编写的界面）
重新打包后，运行 exe 文件就不会再出现多余的 cmd 弹窗了，直接显示程序效果。

怎么添加个性图标

在使用 PyInstaller 打包时，可以通过 -i 参数指定图片作为程序的图标（支持 .ico 格式图片，部分版本也支持 .png 等格式，但推荐用 .ico 以保证兼容性）。
完整打包命令（含图标 + 无控制台）：
bash
pyinstaller -F -w -i 图标文件路径 代码文件路径
参数说明：
-i 图标文件路径：指定程序图标（例如 ./myicon.ico，路径可以是相对路径或绝对路径）
-F：生成单个可执行文件
-w：隐藏控制台窗口
示例：
假设你的图标文件是 happy.ico（和代码文件在同一文件夹），代码文件是 surprise.py，则命令为：
bash
pyinstaller -F -w -i happy.ico surprise.py
注意：
图标文件推荐使用 .ico 格式（如果是其他格式，可先用在线工具转换为 .ico）。
确保图标文件路径正确，否则会打包成功但图标显示为默认样式。
这样打包后，生成的 exe 文件就会带有你指定的图标，且运行时不会出现 cmd 窗口。