🧩 Python 程序打包成 EXE 全面教程

📖 一、PyInstaller 简介

PyInstaller 是最常用的 Python 程序打包工具，可以将 .py 文件及其所有依赖打包成一个可在 Windows 上独立运行的 .exe 文件。

特点：

• 支持范围取决于所用 PyInstaller 版本，安装前核对其 Python 与平台要求
• 无需安装 Python 即可运行打包后的程序
• 可打包为单个文件或文件夹结构
• 支持添加图标、资源文件、隐藏命令行窗口等

⚙️ 二、环境准备

1️⃣ 检查 Python 环境

在命令行输入：

python --version

输出类似：

Python 3.10.13

确保系统能正确识别 Python。

2️⃣ 安装 PyInstaller

python -m pip install pyinstaller

验证安装是否成功：

pyinstaller --version

🧱 三、示例项目结构

假设你的项目如下：

project/
│
├─ main.py              # 主程序
├─ config/
│   └─ settings.json    # 配置文件
└─ images/
    └─ logo.png         # 图片资源

main.py 示例代码：

import json, os, sys

def resource_path(relative_path):
    """获取打包后资源文件的路径"""
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.dirname(os.path.abspath(__file__)), relative_path)

def main():
    config_path = resource_path("config/settings.json")
    with open(config_path, "r", encoding="utf-8") as f:
        data = json.load(f)
    print("配置文件内容：", data)
    input("按回车退出...")

if __name__ == "__main__":
    main()

🚀 四、打包命令详解

🔹 最简单的打包

pyinstaller main.py

输出目录结构：

build/      # 中间构建文件
dist/       # 最终生成的可执行文件所在目录
main.spec   # PyInstaller 配置文件

进入 dist/main/，可看到：

main.exe

🔹 打包成单个 .exe 文件

pyinstaller -F main.py

-F 表示 onefile 模式，将所有依赖打包进单个文件中。

输出结果：

dist/main.exe

🔹 添加程序图标

pyinstaller -F -i icon.ico main.py

图标文件必须是 .ico 格式（可用在线转换工具把 .png 转成 .ico）。

🔹 去除命令行黑框（GUI 程序用）

pyinstaller -F -w main.py

-w 或 --windowed 表示 隐藏控制台窗口。
用于 PyQt5、Tkinter、wxPython 等图形界面应用。
本文的 main.py 使用 print() 和 input()，请保留控制台；直接给这个示例加 -w 可能因标准输入不可用而失败。GUI 程序应改用界面显示和交互。

🔹 自定义生成文件名与输出路径

pyinstaller -F -w -i app.ico -n myApp --distpath build_output main.py

参数说明：

• -n myApp：自定义可执行文件名。
• --distpath：指定输出文件夹（默认是 dist）。

🔹 打包时包含资源文件

pyinstaller -F main.py --add-data "config:config" --add-data "images:images"

解释：

• 当前 PyInstaller 使用 "源路径:目标路径" 形式，SOURCE 和 DEST 用冒号 : 分隔。
• 如果后续版本行为有变化，以当前环境的 python -m PyInstaller --help 为准。
• 打包应在目标操作系统上进行；在 WSL/Linux 运行 PyInstaller 不会直接生成可用的 Windows EXE。
• onefile 模式的内置资源会解压到临时目录，修改它们通常不会保留到下次启动。持久配置应存放到用户可写的独立目录。

打包后：

dist/main.exe

运行时即可自动包含 config/settings.json 和 images/logo.png。

🧩 五、完整打包命令示例

pyinstaller -F -i app.ico -n TrafficMonitor ^
--add-data "config:config" --add-data "images:images" ^
main.py

以下多行命令使用 CMD 的 ^ 续行；PowerShell 中请改为一行执行。app.ico、资源目录需提前准备。

运行完毕后：

dist/TrafficMonitor.exe

双击即可运行；此处保留控制台以支持示例中的输入和输出。

⚡ 六、打包后优化与问题处理

🔸 文件体积太大？

可以用 UPX 压缩：

# 先从 UPX 项目下载适合平台的可执行程序并解压：
# https://upx.github.io/
# 下面的目录需包含 upx 可执行文件
pyinstaller -F main.py --upx-dir "C:\path\to\upx"

🔸 运行时报错：找不到模块

确认缺少的是动态导入后再添加；下面的 your_package 要改成真实导入名：

pyinstaller -F main.py --hidden-import your_package

🔸 资源文件路径问题

使用下面的函数来获取资源路径（推荐放在开头）：

import sys, os

def resource_path(relative_path):
    if hasattr(sys, "_MEIPASS"):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.dirname(os.path.abspath(__file__)), relative_path)

这样在 .exe 中也能正确找到资源。

🧠 七、使用 .spec 文件自定义打包流程

第一次运行 PyInstaller 会生成 main.spec。保留生成的完整内容，包括 Analysis、PYZ 以及 EXE 等相互关联的对象，按需修改对应参数。不要把简化的对象片段当作完整可运行的 spec。

例如，在已有 Analysis(...) 的 datas 参数里配置资源，下面只展示该参数的值：

datas = [
    ('config/settings.json', 'config'),
    ('images/logo.png', 'images'),
]

实际编辑时，将列表放回生成文件原有的 datas= 位置。GUI 项目可以修改生成的 EXE(...) 中的 console=False；本文带 input() 的示例保留 console=True。

之后可以直接运行：

pyinstaller main.spec

这样不必每次输入长长的命令，适合项目固定打包需求。

🔍 八、完整流程总结

🧰 九、进阶技巧

• 批处理打包脚本（保存为 build.bat）：

  @echo off
  echo === 开始打包 ===
  pyinstaller -F -i app.ico -n MyApp --add-data "config:config" main.py
  echo === 打包完成，生成文件在 dist/MyApp.exe ===
  pause

  双击 build.bat 即可一键生成。

✅ 十、示例打包结果

成功后会生成：

dist/
└── MyApp.exe

双击即可直接运行，即使目标计算机上没有安装 Python。