如何用PyInstaller将依赖Jupyter Kernel的Python程序打包为exe？

问题根源 #

PyInstaller默认不会自动打包Jupyter Kernel的配置文件（kernel specs）、关联依赖模块，且打包后的嵌入式Python环境与系统Python路径不匹配，导致Kernel启动后无法正常响应。

具体解决方案 #

• 显式打包Kernel Spec文件
  先通过jupyter kernelspec list命令找到系统中Python Kernel的配置目录（比如Windows下为C:\Users\<用户名>\AppData\Roaming\jupyter\kernels\python3，Linux/Mac下为/usr/local/share/jupyter/kernels/python3）。打包时用--add-data参数将该目录包含到exe中：

  # Windows
  pyinstaller --add-data "C:\Users\<用户名>\AppData\Roaming\jupyter\kernels\python3;jupyter\kernels\python3" your_script.py
  
  # Linux/Mac
  pyinstaller --add-data "/usr/local/share/jupyter/kernels/python3:jupyter/kernels/python3" your_script.py
  

• 动态设置Jupyter数据目录
  在应用启动代码中添加环境变量，让jupyter_client能找到打包后的Kernel Spec：

  import os
  import sys
  
  if getattr(sys, 'frozen', False):
      # 打包后PyInstaller会在sys._MEIPASS中存放临时解压的资源
      jupyter_data_dir = os.path.join(sys._MEIPASS, 'jupyter')
      os.environ['JUPYTER_DATA_DIR'] = jupyter_data_dir
  

• 修正Kernel的Python解释器路径
  默认Kernel配置文件中的Python路径指向系统Python，打包后需要替换为嵌入式的Python（即当前exe对应的解释器）：

  import json
  
  if getattr(sys, 'frozen', False):
      kernel_spec_path = os.path.join(jupyter_data_dir, 'kernels', 'python3', 'kernel.json')
      with open(kernel_spec_path, 'r', encoding='utf-8') as f:
          spec_content = json.load(f)
      # 替换argv中的Python路径为当前执行程序
      spec_content['argv'][0] = sys.executable
      with open(kernel_spec_path, 'w', encoding='utf-8') as f:
          json.dump(spec_content, f, indent=2)
  

• 强制添加缺失的依赖模块
  部分jupyter相关模块可能不会被PyInstaller自动检测到，打包时用--hidden-import补充：

  pyinstaller --hidden-import jupyter_core --hidden-import ipykernel --hidden-import ipython_genutils --hidden-import traitlets your_script.py
  

• 调试Kernel启动日志
  如果仍报错，给KernelManager添加日志文件，查看具体失败原因：

  from jupyter_client import KernelManager
  
  km = KernelManager()
  km.log_file = 'kernel_debug.log'
  km.start_kernel()
  

  运行exe后查看kernel_debug.log，定位是依赖缺失、路径错误还是权限问题。

内容的提问来源于stack exchange，提问作者Tom Brady