Windows下PyInstaller打包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

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