Windows下PyInstaller打包Python的完整教程

目录

• 前言
• 为什么选择 PyInstaller
• 工作原理快览
• 环境准备（建议使用虚拟环境）
• 快速入门（命令行应用）
• GUI 应用打包（隐藏控制台）
• 资源与路径处理
• 依赖与导入问题
• 常用模式与建议
• .spec 文件进阶（可定制构建）
• 图标与版本信息（Windows）
• 代码签名与可信度（Windows）
• 常见错误排查
• 构建与发布建议
• 常用命令速查

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

适用：将 Python 脚本打包为无需 Python 环境的可执行文件。

优势：自动分析依赖、跨平台（需在目标平台上构建）、支持单文件/目录两种分发方式。

解析入口脚本的导入依赖，收集 .py、数据文件、动态库。

生成引导器（bootloader）+ 内置 Python 解释器 + 资源包。

--onefile：运行时临时解压到缓存目录再执行；--onedir：直接从目录运行。

# 1) 新建并激活 venv（PowerShell）
python -m venv .venv
..venvScriptsActivate.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 "dataconfig.json;data" `
  app.py

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

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

pyinstaller -F -w -n MyApp -i assetsapp.ico app.py

读取资源时使用上方 resource_path()，兼容开发与打包。

复制资源：

• 数据：--add-data "src_path;dest_dir"
• 二进制：--add-binary "src_path;dest_dir"

示例：

pyinstaller -F `
  --add-data "assetslogo.png;assets" `
  --add-binary "binhelper.dll;bin" `
  app.py

隐式导入未被自动检测：--hidden-import some_pkg.submod

添加搜索路径（非标准包位置）：--paths pathtolibs

缩小体积（排除不需要的模块）：--exclude-module tests

--onefile：易分发；启动需解压，体积更大。

--onedir：启动快；以文件夹分发，便于增量更新。

科学计算（numpy/pandas/scipy）通常推荐 --onedir 以提升启动速度。

• 首次打包会生成 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 等

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

图标：-i pathtoicon.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 SDK 的 signtool）：

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

“failed to execute script”：从命令行运行 distxxx.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 assetsapp.ico app.py
# 追加资源/二进制
pyinstaller -F --add-data "datacfg.json;data" --add-binary "binx.dll;bin" app.py
# 指定隐藏导入与路径
pyinstaller -F --hidden-import pkg.sub --paths extralibs app.py
# 清理并覆盖输出
pyinstaller --clean --noconfirm -F app.py
# 使用 spec 构建
pyinstaller app.spec

到此这篇关于Windows下PyInstaller打包Python的完整教程的文章就介绍到这了,更多相关PyInstaller打包Python内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• 使用PyInstaller打包Python项目过程
• 使用PyInstaller打包Python脚本为可执行文件的详细指南
• PyInstaller将Python项目打包为exe的踩坑记录
• python用PyInstaller打包成windows可执行的exe(细致版)
• 使用PyInstaller将Python代码打包成独立可执行文件详细步骤
• Python使用pyinstaller打包成.exe文件执行后闪退的图文解决办法
• PyInstaller将Python脚本打包为.exe可执行文件的步骤详解
• Python pyinstaller打包exe最新完整图文教程