Pyinstaller - Python桌面应用打包的首选工具 - 详解

大家好，我是唐叔。上次我们讲解了 Python+Web构建桌面应用的最佳选择 - Pywebview，那么写好的Python程序，如何在别人的电脑上运行？总不能要求每个人都安装Python、配置环境吧？这时候，PyInstaller 就派上用场了。

文章目录

• • 一、PyInstaller 是什么？
  • 二、安装PyInstaller
  • 三、快速上手：打包第一个应用
  • • 3.1 基础打包命令
    • 3.2 打包为单个文件
    • 3.3 隐藏命令行窗口
    • 3.4 自定义应用图标
  • 四、进阶技巧：优化与实战
  • • 4.1 解决打包文件过大问题
    • 4.2 多程序文件打包
    • 4.3 静态资源打包（如图片、HTML）
  • 五、总结

一、PyInstaller 是什么？

PyInstaller 是一个强大的Python应用程序打包工具，它能将你的Python脚本及其所有依赖项（包括解释器、模块、库等）打包成一个独立的可执行文件（如.exe）。用户无需安装Python，双击即可运行！

原理小贴士：PyInstaller 会递归分析你的代码，找出所有被导入的模块，确保所有依赖都被正确打包。

适用场景：

• 开发GUI桌面应用（如PyQt、Tkinter、pywebview）
• 制作小工具或脚本，供非技术人员使用
• 需要跨Windows、macOS、Linux分发Python程序

二、安装PyInstaller

安装非常简单，只需一行命令：

pip install pyinstaller

建议在虚拟环境中安装，避免污染全局环境。

三、快速上手：打包第一个应用

我们以一个简单的 pywebview 示例为例：

import webview
if __name__ == '__main__':
webview.create_window('Demo', 'https://pyinstaller.org')
webview.start()

保存为 demo.py，接下来我们开始打包。

3.1 基础打包命令

pyinstaller demo.py

执行后，会在当前目录生成 dist 文件夹，里面就是打包好的应用程序。你可以将整个 dist 文件夹发给别人使用。

3.2 打包为单个文件

如果你不想发整个文件夹，可以使用 -F 参数：

pyinstaller -F demo.py

这样就会生成一个独立的 .exe 文件，方便分发。

✅ 提示：--onefile 是 -F 的全称，效果相同。

3.3 隐藏命令行窗口

如果你打包的是GUI程序，不希望出现命令行窗口，可以使用 -w 参数：

pyinstaller -F -w demo.py

✅ 提示：-w、--windowed、--noconsole 三者等价。

3.4 自定义应用图标

使用 -i 参数可以指定图标文件（需为 .ico 格式）：

pyinstaller -F -w -i logo.ico demo.py

四、进阶技巧：优化与实战

4.1 解决打包文件过大问题

打包后文件太大？最常见的原因是打包了不必要的依赖。

方法一：手动排除冗余模块

例如，使用 pywebview 时，默认会打包 PyQt，导致体积暴增。我们可以手动排除：

pyinstaller -F -w --exclude-module PyQt6 demo.py

从186MB降到13.7MB，效果显著！

方法二：使用独立虚拟环境

如果你不确定哪些模块是冗余的，建议在干净的虚拟环境中打包：

python -m venv myenv
myenv\Scripts\activate  # Windows
pip install pyinstaller pywebview
pyinstaller -F -w demo.py

这样打包出来的文件只有10MB，更小，也更干净。

有关python独立环境创建的详细教程，唐叔后续将专门章节展开介绍，敬请期待。

4.2 多程序文件打包

如果你的项目有多个 .py 文件，不用担心，PyInstaller 会自动递归分析依赖，并将其一并打包。

例如：

project/├── demo.py└── module/└── asset.py

只需打包主文件：

pyinstaller -F -w demo.py

PyInstaller 会自动识别并打包 asset.py。

当然你也可以使用 --collect-submodules 手动指定打包模块，这里就不展开了。

4.3 静态资源打包（如图片、HTML）

如果你的程序使用了外部文件（如图片、HTML、配置文件），可以使用 --add-data 参数：

pyinstaller -F -w --add-data "index.html;." demo.py

需要注意： 在代码中，你需要使用 pathlib 或 sys._MEIPASS 来正确获取资源路径：

import pathlib
folder = pathlib.Path(__file__).parent.resolve()
with open(folder / 'index.html', 'r', encoding='utf-8') as f:
html = f.read()

这样就能在打包后正确读取静态文件了。未正确获取资源路径，可能会报错：FileNotFoundError。

五、总结

PyInstaller 是Python开发者必备的打包工具，无论是GUI程序、命令行工具，还是带资源文件的项目，它都能胜任。

本文要点回顾：

• 使用 -F 打包为单文件，-w 隐藏命令行
• 使用 -i 自定义图标
• 通过 --exclude-module 或虚拟环境优化体积
• 使用 --add-data 打包静态资源

如果你正在学习Python桌面开发，或希望将自己的脚本分享给他人，PyInstaller 绝对是你的首选工具。

附：资源&参考链接

• PyInstaller 官网
• PyInstaller GitHub 源码
• Pyinstaller打包，彻底解决图片、数据路径问题 - 知乎
• pyinstaller遇到的坑：–add-data参数中的文件被打包进_internal文件夹

如果有任何问题，欢迎在评论区留言，唐叔会尽力解答！