将 Python 程序打包为可执行文件（Windows & Linux）

前提条件

在开始之前，请根据目标平台准备开发环境：

所有平台必备

  • Python 3.x
  • pip（Python包管理工具）

Windows 额外要求

  • 建议使用 PowerShell 或 CMD 命令行工具

Linux 额外要求

  • 需要安装基础开发工具包（以 Arch Linux 为例）：
    1
    sudo pacman -S base-devel zlib

安装 PyInstaller

1
2
3
4
5
6
7
# 通用安装命令
pip install pyinstaller

# Linux 系统建议使用虚拟环境
python -m venv venv
source venv/bin/activate
pip install pyinstaller

打包程序

Windows 系统

  1. 进入脚本目录

    1
    cd C:\path\to\your\script

  2. 生成可执行文件

    1
    pyinstaller --onefile --windowed your_script.py

  3. 获取生成文件

    • 在 dist/ 目录中找到 .exe 文件
    • 注意：首次打包可能较慢（5-30秒）

Linux 系统

  1. 进入脚本目录

    1
    cd /path/to/your/script

  2. 生成可执行文件

    1
    pyinstaller --onefile your_script.py

  3. 设置执行权限

    1
    chmod +x dist/your_script

  4. 运行测试

    1
    ./dist/your_script

跨平台注意事项

部分参数

  • --onefile：生成单文件可执行程序
  • --windowed（仅Windows）：隐藏控制台窗口
  • --icon：自定义程序图标（Windows使用.ico，Linux建议.svg或.png）
  • --add-data：添加额外资源文件（例：--add-data 'assets/*:assets'）

路径处理技巧

1
2
3
4
5
6
7
8
9
10
11
12
# 在代码中使用资源路径兼容写法
import sys
import os

def resource_path(relative_path):
    """ 获取资源的绝对路径"""
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

# 使用示例
icon_path = resource_path('app_icon.ico')

高级打包选项

压缩优化

1
2
3
4
# 使用UPX压缩（需提前安装）
# Windows：下载 upx.exe 添加到PATH
# Arch Linux：sudo pacman -S upx
pyinstaller --onefile --upx-dir=/path/to/upx your_script.py

排除不需要的模块

1
pyinstaller --onefile --exclude-module matplotlib your_script.py

指定Python解释器

1
2
# 确保使用正确的Python版本
pyinstaller --python /usr/bin/python3.8 your_script.py

测试与分发

Windows 测试

  • 直接双击.exe文件运行
  • 若出现闪退，可在命令行中运行查看错误信息

Linux 测试

1
2
3
4
5
# 检查依赖库
ldd dist/your_script

# 查看控制台输出
./dist/your_script --debug

通用验证方法

  1. 在虚拟机/干净系统中测试
  2. 检查临时解压目录（Windows：%TEMP%\_MEIxxxxx，Linux：/tmp/_MEIxxxxx）
  3. 使用--log-level DEBUG参数查看详细打包过程

常见问题解决

Q：程序找不到数据文件

  • 确保使用--add-data添加资源文件
  • 在代码中使用前文提到的resource_path()方法

Q：出现 ModuleNotFoundError

  • 使用--hidden-import指定隐藏依赖
    1
    pyinstaller --hidden-import sklearn.utils._weight_vector your_script.py

Q：Linux打包后文件体积过大

  • 使用UPX压缩
  • 排除不需要的库（--exclude-module）
  • 使用 Alpine Linux 进行最小化打包

Q：图形界面程序无法启动

  • Windows：安装VC++运行库
  • Linux：安装GTK/Qt依赖
    1
    2
    # 对于PyQt5程序
    sudo pacman -S qt5-base

版本兼容性

Python 版本 PyInstaller 推荐版本 注意事项
3.6-3.7 4.x 停止维护版本
3.8-3.10 5.x 主流支持版本
3.11+ 6.x 需要最新PyInstaller