• 🌸 欢迎来到Python办公自动化专栏—Python处理办公问题，解放您的双

• 💻 个人主页——>个人主页欢迎访问

• 😸 Github主页——>Github主页欢迎访问

• ❓ 知乎主页——>知乎主页欢迎访问

• 🏳️‍🌈 CSDN博客主页：请点击——> 一晌小贪欢的博客主页求关注

• 👍 该系列文章专栏：请点击——>Python办公自动化专栏求订阅

• 🕷 此外还有爬虫专栏：请点击——>Python爬虫基础专栏求订阅

• 📕 此外还有python基础专栏：请点击——>Python基础学习专栏求订阅

• 文章作者技术和水平有限，如果文中出现错误，希望大家能指正🙏

• ❤️ 欢迎各位佬关注！ ❤️

前言

一篇掌握 PyInstaller：从零到可分发的 .exe。覆盖安装、常用参数、资源文件、GUI、.spec 进阶、签名与排错。

为什么选择 PyInstaller

• 适用：将 Python 脚本打包为无需 Python 环境的可执行文件。
• 优势：自动分析依赖、跨平台（需在目标平台上构建）、支持单文件/目录两种分发方式。

工作原理快览

• 解析入口脚本的导入依赖，收集 .py、数据文件、动态库。
• 生成引导器（bootloader）+ 内置 Python 解释器 + 资源包。
• --onefile：运行时临时解压到缓存目录再执行；--onedir：直接从目录运行。

环境准备（建议使用虚拟环境）

# 1) 新建并激活 venv（PowerShell）
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# 2) 升级基本工具
pip install -U pip wheel
# 3) 安装 PyInstaller
pip install -U pyinstaller

快速入门（命令行应用）

示例 app.py：

# app.py
import sys, json
from pathlib import Path

def resource_path(relative):
    base = getattr(sys, "_MEIPASS", Path(__file__).parent)  # onefile 下的临时目录
    return Path(base) / relative

def main():
    print("Hello PyInstaller!")
    cfg = json.loads(resource_path("data/config.json").read_text(encoding="utf-8"))
    print("config:", cfg)

if __name__ == "__main__":
    main()

准备数据文件：data/config.json

{"app_name":"Hello","debug":true}

打包（单文件）：

pyinstaller -F -n hello `
  --add-data "data\config.json;data" `
  app.py

• Windows 的 --add-data 使用分号 ;（Linux/macOS 用冒号 :）。
• 输出目录：dist/hello.exe（成品）、build/（临时）、hello.spec（构建配置）。

GUI 应用打包（隐藏控制台）

• 控制台程序（默认）：--console
• GUI 程序（隐藏控制台）：-w 或 --windowed

pyinstaller -F -w -n MyApp -i assets\app.ico app.py

资源与路径处理

• 读取资源时使用上方 resource_path()，兼容开发与打包。
• 复制资源：
  • 数据：--add-data "src_path;dest_dir"
  • 二进制：--add-binary "src_path;dest_dir"
    示例：

pyinstaller -F `
  --add-data "assets\logo.png;assets" `
  --add-binary "bin\helper.dll;bin" `
  app.py

依赖与导入问题

• 隐式导入未被自动检测：--hidden-import some_pkg.submod
• 添加搜索路径（非标准包位置）：--paths path\to\libs
• 缩小体积（排除不需要的模块）：--exclude-module tests

常用模式与建议

• --onefile：易分发；启动需解压，体积更大。
• --onedir：启动快；以文件夹分发，便于增量更新。
• 科学计算（numpy/pandas/scipy）通常推荐 --onedir 以提升启动速度。

.spec 文件进阶（可定制构建）

• 首次打包会生成 your_app.spec，可编辑以添加资源、修改参数。
• 使用 .spec 构建：pyinstaller your_app.spec
• 简例（核心片段，实际文件更长）：

# hello.spec（示意）
datas = [("data\\config.json", "data"), ("assets\\logo.png", "assets")]
# 在 Analysis(...) 中传入 datas；在 EXE(...) 中设置 name、icon、console 等

适合复杂资源收集、多个入口脚本、精细控制压缩/排除。

图标与版本信息（Windows）

• 图标：-i path\to\icon.ico
• 版本资源：--version-file version_info.txt
version_info.txt 示例（节选）：

VSVersionInfo(
  FileVersion='1.0.0.0',
  ProductVersion='1.0.0.0',
  FileDescription='MyApp',
  CompanyName='Your Company',
)

代码签名与可信度（Windows）

• 未签名的可执行文件更易被杀毒拦截。
• 使用证书签名（Windows SDK 的 signtool）：

signtool sign /a /fd sha256 /tr http://timestamp.digicert.com /td sha256 `
  dist\MyApp.exe

常见错误排查

• “failed to execute script”：从命令行运行 dist\xxx.exe 观察错误；尝试 --log-level DEBUG。
• 启动缓慢（单文件）：改用 --onedir 或减少资源体积；可选安装 UPX 压缩（可能触发杀毒）。
• 缺少 DLL：确认依赖是否在同目录或通过 --add-binary 复制；必要时在代码中用 os.add_dll_directory() 设置路径（Python 3.8+）。
• 打包前清理缓存：pyinstaller --clean -F app.py

构建与发布建议

• 固定依赖版本：requirements.txt；在干净环境重装后再打包。
• 在目标平台上构建（Windows 打包 Windows，macOS 打包 macOS）。
• 小步验证：先 --onedir 验证，再切换 --onefile。
• CI/CD：在流水线中使用同样的命令和固定版本以保证可重复。

常用命令速查

# 单文件（控制台）
pyinstaller -F -n app app.py
# 单文件（GUI，无控制台）
pyinstaller -F -w -n app -i assets\app.ico app.py
# 追加资源/二进制
pyinstaller -F --add-data "data\cfg.json;data" --add-binary "bin\x.dll;bin" app.py
# 指定隐藏导入与路径
pyinstaller -F --hidden-import pkg.sub --paths extra\libs app.py
# 清理并覆盖输出
pyinstaller --clean --noconfirm -F app.py
# 使用 spec 构建
pyinstaller app.spec

参考

• 官方文档：https://pyinstaller.org/en/stable/
• 问答与案例：GitHub Issues、Stack Overflow（搜索具体库名 + PyInstaller）

—— 完 ——

• 希望对初学者有帮助；致力于办公自动化的小小程序员一枚

• 希望能得到大家的【❤️一个免费关注❤️】感谢！

• 求个 🤞 关注 🤞 +❤️ 喜欢 ❤️ +👍 收藏 👍

• 此外还有办公自动化专栏，欢迎大家订阅：Python办公自动化专栏

• 此外还有爬虫专栏，欢迎大家订阅：Python爬虫基础专栏

• 此外还有Python基础专栏，欢迎大家订阅：Python基础学习专栏