pyinstaller：将Python 3脚本打包为可执行程序

原创已于 2025-12-08 23:31:16 修改 · 1.2k 阅读

26 ·

CC 4.0 BY-SA版权

文章标签：

#python #开发语言 #pyinstaller

于 2025-04-29 11:22:35 首次发布

编程学习笔记专栏收录该内容

190 篇文章

订阅专栏

部署运行你感兴趣的模型镜像

诸神缄默不语-个人技术博文与视频目录

这个包的使用场景一般是你已经把脚本写好了，尤其是有GUI界面了，然后你现在希望把这个脚本给别人用，这种时候pyinstaller就可以直接帮你把脚本打包成一个可执行文件（Windows平台的话就是exe文件），这样就可以在没有Python环境或者怎么怎么样的电脑环境下直接运行了。

1. 安装pyinstaller

pip install pyinstaller

2. 打包命令

pyinstaller your_script.py
会自动创建dist文件夹，底下的内容就是可以直接转给别人的程序了。

参数：

--onefile：只生成一个可执行文件（exe）。运行时，文件会解压到临时目录并加载依赖。适用于需要简化分发的场景（如分享GUI程序给非技术用户）。启动时需要解压所有内容到临时目录（如 sys._MEIPASS），可能导致首次启动较慢。
使用 --onefile 时，需通过 sys._MEIPASS 访问打包的资源文件（如图片、配置文件），否则路径会指向临时目录导致错误。
获取方法示例一：

import sys, os
def resource_path(relative_path):
    try:
        base_path = sys._MEIPASS  # 临时目录
    except Exception:
        base_path = os.path.abspath(".")
    return os.path.join(base_path, relative_path)

获取方法示例二：

import sys
import os

def get_resource_path(relative_path):
    if getattr(sys, 'frozen', False):  # 判断是否在打包环境中运行
        base_path = sys._MEIPASS
    else:
        base_path = os.path.abspath(".")  # 开发环境当前目录
    return os.path.join(base_path, relative_path)

而不加 --onefile 时，资源文件可直接通过相对路径访问

-F 生成一个可执行文件
-D 生成一个目录（包含多个文件）作为可执行文件
--windowed 或 -w：运行exe时，不显示命令行窗口（仅对Windows有效），适用于图形界面（GUI）程序
--add-data "data_list.txt;."：指定资源文件的路径和在可执行文件中的相对路径
Windows 使用分号 ; 分隔路径，Linux/macOS 使用冒号 :
--hidden-import pandas._libs.tslibs.timedeltas --hidden-import openpyxl
pyinstaller会默认打包显式调用的包。这两个是因为我用了pandas，openpyxl是pandas读Excel文件的引擎，所以也得跟着装。
--name 或 -n：指定程序名
--icon 或 -i：指定生成的可执行文件的图标文件
--distpath 该参数后跟可执行文件的路径

3. 常见错误

1. pathlib包与pyinstaller不兼容

ERROR: The 'pathlib' package is an obsolete backport of a standard library package and is incompatible with PyInstaller. Please remove this package (located in D:\anacondasoftware\envs\env_name\lib\site-packages) using
    conda remove
then try again.

因为我不敢直接conda remove（网上确实也有人conda remove后环境被搞乱了的），所以采取的解决方案是直接新建了一个Anaconda虚拟环境，然后就好了：

conda create -n pyinstaller_env python=3.10
conda activate pyinstaller_env
pip install pyinstaller pandas openpyxl

……2025.5.15逆天补充：在现有的pyinstaller_env里面又出现了一样的bug，我试图执行conda remove pathlib直接给我报这个错：

Collecting package metadata (repodata.json): done
Solving environment: failed

PackagesNotFoundError: The following packages are missing from the target environment:
  - pathlib

抽象。解决方案是又新建了一个Anaconda虚拟环境用来打包……

2. 报各种找不到文件错误

如JioNLP包的util\zip_file.py，是这样处理的，就是根据可执行文件的相对路径来找文件，就在解压出可执行文件后把所需文件放在指定位置就可以：

if hasattr(sys, 'frozen'):
    DIR_PATH = os.path.dirname(os.path.realpath(sys.executable))

还有dictionary\dictionary_loader.py，这个原代码是DIR_PATH = os.path.dirname(os.path.abspath(__file__))，问题在于就是pyinstaller打包没有把这些所需文件打进来。我不知道原理是什么，总之解决方案是：

if getattr(sys, 'frozen', False):
    # 打包环境
    DIR_PATH = os.path.join(os.path.dirname(sys.executable), 'dictionary')
else:
    DIR_PATH = os.path.dirname(os.path.abspath(__file__))