这个包的使用场景一般是你已经把脚本写好了，尤其是有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.

我采取的解决方案是直接新建了一个Anaconda虚拟环境，然后就好了：

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

网上也有人直接执行conda remove pathlib能够解决问题，但是我这么干会报这个错：

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

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

抽象。

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__))

大家就一起在可执行文件附近的文件夹里顶峰相见吧！！！

3. 结合uv

我选择的方式是：先运行uv sync把当前虚拟环境同步到.venv下。
然后如果你在编辑器里，一般来说默认已经进入了虚拟环境。如果没有进入就手动运行.venv/Scripts/activate
在虚拟环境下运行pyinstaller命令就可以了

参考资料：Using pyinstaller with uv : r/learnpython^[1]

4. 本文撰写过程中参考的其他网络资料

1. 1. Python打包工具 Pyinstaller使用教程^[2]

引用链接

[1] Using pyinstaller with uv : r/learnpython: https://www.reddit.com/r/learnpython/comments/1jtq8d1/using_pyinstaller_with_uv/
[2] Python打包工具 Pyinstaller使用教程: https://www.cnblogs.com/ubirdy/p/18812950