Pyinstaller打包exe运行报Numpy C-extensions加载错误

已验证可落地的排查修复步骤 #

• 修正打包命令的--paths参数配置，不要只填写虚拟环境的Lib/site-packages路径，必须额外补充两个路径：
  1. Python 3.9安装根目录下的DLLs文件夹路径，默认安装路径通常为C:\Users\当前用户名\AppData\Local\Programs\Python\Python39\DLLs
  2. 虚拟环境内Lib\site-packages\numpy\core文件夹路径
     完整参考打包命令如下：

  pyinstaller --onefile --paths "C:\path\to\your\venv\Lib\site-packages" --paths "C:\path\to\Python39\DLLs" --paths "C:\path\to\your\venv\Lib\site-packages\numpy\core" app.py
  

• 显式声明隐式导入依赖，解决Pyinstaller静态扫描漏识别numpy C扩展的问题。在打包命令中追加--hidden-import参数指定numpy核心模块：

  pyinstaller --onefile --paths "上述三个路径" --hidden-import numpy.core._multiarray_umath --hidden-import numpy.core._dtype_ctypes --hidden-import numpy._core app.py
  

• 校验版本兼容性：Pyinstaller对numpy 1.26.x、2.x版本的单文件打包支持存在已知缺陷，Python 3.9环境建议安装经过大量验证的1.23.5稳定版numpy后重新打包：

  # 激活虚拟环境后执行
  pip uninstall numpy -y
  pip install numpy==1.23.5
  

• 确认Pyinstaller安装位置：不要使用全局环境安装的Pyinstaller打包虚拟环境项目，全局Pyinstaller会默认关联全局Python的依赖链，和虚拟环境内的numpy版本不匹配时必然触发DLL加载错误。需要先激活虚拟环境，在虚拟环境内重新安装Pyinstaller后再执行打包操作。
• 单文件模式特殊适配：如果上述操作后--onefile模式仍报错，可以先测试--onedir文件夹模式打包，若文件夹模式运行正常，说明是单文件模式临时解压路径的DLL搜索顺序问题。在项目代码最顶部（所有numpy导入语句之前）添加如下路径配置代码即可：

  import sys
  import os
  if hasattr(sys, '_MEIPASS'):
      os.add_dll_directory(sys._MEIPASS)
      numpy_core_dir = os.path.join(sys._MEIPASS, 'numpy', 'core')
      if os.path.exists(numpy_core_dir):
          os.add_dll_directory(numpy_core_dir)
  # 后续再编写import numpy及其他业务代码
  

注：执行打包前建议先删除之前打包生成的build、dist文件夹和.spec文件，避免旧缓存干扰打包结果。

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