PyInstaller打包Python应用操作备忘

引言

在日常开发中，我们经常需要将Python程序分发给没有安装Python环境的用户。PyInstaller是一个强大的工具，它可以将Python程序打包成独立的可执行文件，支持Windows、Linux和macOS等多个平台。本文将详细介绍如何使用PyInstaller打包Python程序，包括基本用法、高级配置以及常见问题的解决方案。

目录

1. PyInstaller简介与安装

2. 基本打包方法

3. 打包演示：一个简单的GUI应用

4. 高级配置选项

5. 处理打包中的常见问题

6. 优化打包结果

7. 总结

1. PyInstaller简介与安装

什么是PyInstaller?

PyInstaller是一个将Python程序转换为独立可执行文件的程序。它会分析你的Python代码，收集所有必要的依赖项（包括Python解释器本身），然后将它们打包到一个文件夹或单个可执行文件中。

安装PyInstaller

安装PyInstaller非常简单，只需使用pip：

bash

pip install pyinstaller

安装完成后，可以通过以下命令验证安装是否成功：

bash

pyinstaller --version

2. 基本打包方法

最简单的打包命令

假设我们有一个名为hello.py的简单Python脚本：

python

# hello.py
print("Hello, PyInstaller!")

要将其打包为可执行文件，只需运行：

bash

pyinstaller hello.py

这将在当前目录下生成两个文件夹：

• build/ - 包含临时文件和日志

• dist/ - 包含生成的可执行文件

生成单个可执行文件

默认情况下，PyInstaller会生成一个包含多个文件的文件夹。要生成单个可执行文件，可以使用--onefile选项：

bash

pyinstaller --onefile hello.py

隐藏控制台窗口（仅Windows）

对于GUI应用程序，你可能希望隐藏控制台窗口：

bash

pyinstaller --onefile --windowed hello.py

3. 打包演示：一个简单的GUI应用

让我们通过一个更实际的例子来演示PyInstaller的使用。我们将创建一个简单的PyQt5 GUI应用，然后打包它。

示例代码：简单的文本编辑器

python

# text_editor.py
import sys
from PyQt5.QtWidgets import (QApplication, QMainWindow, QTextEdit, QFileDialog, QAction)class TextEditor(QMainWindow):def __init__(self):super().__init__()self.initUI()def initUI(self):self.textEdit = QTextEdit()self.setCentralWidget(self.textEdit)# 创建菜单栏menubar = self.menuBar()fileMenu = menubar.addMenu('文件')# 添加打开动作openAction = QAction('打开', self)openAction.triggered.connect(self.openFile)fileMenu.addAction(openAction)# 添加保存动作saveAction = QAction('保存', self)saveAction.triggered.connect(self.saveFile)fileMenu.addAction(saveAction)# 设置窗口属性self.setGeometry(300, 300, 800, 600)self.setWindowTitle('简易文本编辑器')self.show()def openFile(self):filename, _ = QFileDialog.getOpenFileName(self, '打开文件')if filename:with open(filename, 'r', encoding='utf-8') as f:self.textEdit.setText(f.read())def saveFile(self):filename, _ = QFileDialog.getSaveFileName(self, '保存文件')if filename:with open(filename, 'w', encoding='utf-8') as f:f.write(self.textEdit.toPlainText())if __name__ == '__main__':app = QApplication(sys.argv)editor = TextEditor()sys.exit(app.exec_())

打包GUI应用

首先确保安装了PyQt5：

bash

pip install pyqt5

然后打包我们的文本编辑器：

bash

pyinstaller --onefile --windowed --icon=app.ico text_editor.py

这里使用了几个新选项：

• --windowed - 防止在Windows上显示控制台窗口

• --icon=app.ico - 为可执行文件设置图标（需要准备一个.ico文件）

处理数据文件和资源

如果你的应用使用了外部资源（如图片、配置文件等），PyInstaller默认不会包含它们。你需要使用--add-data选项：

bash

pyinstaller --onefile --windowed --add-data "assets/*;assets" text_editor.py

在代码中，你需要使用sys._MEIPASS来访问这些资源：

python

import sys
import os
from PyQt5.QtGui import QIcondef resource_path(relative_path):""" 获取资源的绝对路径。用于PyInstaller打包后访问资源文件 """if hasattr(sys, '_MEIPASS'):return os.path.join(sys._MEIPASS, relative_path)return os.path.join(os.path.abspath("."), relative_path)# 使用示例
icon = QIcon(resource_path("assets/icon.png"))

4. 高级配置选项

使用.spec文件

当你第一次运行PyInstaller时，它会生成一个.spec文件。这个文件包含了所有的打包配置，你可以直接修改它而不是使用命令行选项。

生成.spec文件：

bash

pyinstaller text_editor.py

然后你可以编辑text_editor.spec文件，例如：

python

# -*- mode: python ; coding: utf-8 -*-block_cipher = Nonea = Analysis(['text_editor.py'],pathex=['/path/to/your/project'],binaries=[],datas=[('assets/*', 'assets')],hiddenimports=[],hookspath=[],runtime_hooks=[],excludes=[],win_no_prefer_redirects=False,win_private_assemblies=False,cipher=block_cipher,noarchive=False)
pyz = PYZ(a.pure, a.zipped_data,cipher=block_cipher)
exe = EXE(pyz,a.scripts,a.binaries,a.zipfiles,a.datas,[],name='text_editor',debug=False,bootloader_ignore_signals=False,strip=False,upx=True,upx_exclude=[],runtime_tmpdir=None,console=False,icon='app.ico')

然后直接使用.spec文件进行打包：

bash

pyinstaller text_editor.spec

常用命令行选项

选项	描述
--onefile	打包成单个可执行文件
--onedir	打包成一个目录（默认）
--windowed	不显示控制台窗口（Windows/Mac）
--noconsole	不显示控制台窗口（Linux）
--name	设置可执行文件名称
--icon	设置可执行文件图标
--add-data	添加非Python文件
--add-binary	添加二进制文件
--hidden-import	添加PyInstaller无法检测到的隐式导入
--exclude-module	排除特定模块
--upx-dir	指定UPX压缩工具目录

处理隐藏导入

有时PyInstaller无法检测到所有的依赖项，特别是那些动态导入的模块。这时你需要使用--hidden-import选项：

bash

pyinstaller --hidden-import=module_name your_script.py

5. 处理打包中的常见问题

问题1：打包后的程序无法找到资源文件

解决方案：
使用sys._MEIPASS来访问资源文件，如前文所示。

问题2：打包后的程序体积过大

解决方案：

1. 使用UPX压缩：

   bash

   pyinstaller --onefile --upx-dir=/path/to/upx your_script.py

2. 排除不必要的模块：

   bash

   pyinstaller --exclude-module=unnecessary_module your_script.py

问题3：打包时出现"ModuleNotFoundError"

解决方案：

1. 使用--hidden-import添加缺失的模块

2. 确保所有依赖已正确安装

问题4：打包后的程序启动缓慢

解决方案：

1. 使用--onedir而不是--onefile（单个文件解压需要时间）

2. 减少依赖项数量

6. 优化打包结果

减少可执行文件大小

• 使用虚拟环境：创建一个干净的虚拟环境，只安装必要的依赖

• 排除不必要的模块：使用--exclude-module

• 使用UPX压缩

提高启动速度

• 避免使用--onefile，特别是对于大型应用

• 减少启动时加载的模块数量

添加版本信息（Windows）

创建一个版本信息文件（如version_info.txt）：

text

# UTF-8
#
# For more details about fixed file info 'ffi' see:
# https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource
# Fixed file info will always begin with a signature of 0xFEEF04BD
# and will always have a zeros for structure versions.VSVersionInfo(ffi=FixedFileInfo(filevers=(1, 0, 0, 0),prodvers=(1, 0, 0, 0),mask=0x3f,flags=0x0,OS=0x40004,fileType=0x1,subtype=0x0,date=(0, 0)),kids=[StringFileInfo([StringTable(u'040904B0',[StringStruct(u'CompanyName', u'Your Company'),StringStruct(u'FileDescription', u'Your Application Description'),StringStruct(u'FileVersion', u'1.0.0.0'),StringStruct(u'InternalName', u'YourApp'),StringStruct(u'LegalCopyright', u'Copyright © 2023 Your Company'),StringStruct(u'OriginalFilename', u'YourApp.exe'),StringStruct(u'ProductName', u'Your Product'),StringStruct(u'ProductVersion', u'1.0.0.0')])]), VarFileInfo([VarStruct(u'Translation', [1033, 1200])])]
)

然后使用--version-file选项：

bash

pyinstaller --version-file=version_info.txt your_script.py

7. 总结

PyInstaller是一个功能强大且灵活的工具，可以将Python程序打包为独立的可执行文件。通过本文的介绍，你应该已经掌握了：

1. PyInstaller的基本使用方法

2. 如何打包包含资源文件的GUI应用

3. 高级配置选项和.spec文件的使用

4. 常见问题的解决方案

5. 优化打包结果的技巧

记住，完美的打包通常需要一些调试和调整，特别是对于复杂的项目。当遇到问题时，PyInstaller的详细文档和活跃的社区是宝贵的资源。

希望这篇指南能帮助你顺利地将Python程序打包并分享给他人！