使用py2exe打包PySide6 Python GUI程序时触发FileNotFoundError

问题现象 #

使用py2exe打包PySide6 GUI程序后，运行生成的exe时出现如下错误：

Traceback (most recent call last):
  File "main.py", line 3, in <module>
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "zipextimporter.pyc", line 167, in exec_module
  File "PySide6\__init__.pyc", line 123, in <module>
  File "PySide6\__init__.pyc", line 111, in _find_all_qt_modules
FileNotFoundError: [WinError 3] Path not found: 'C:\\Users\\...\\Documents\\gui\\dist\\library.zip\\PySide6'

原因分析 #

py2exe的bundle_files=1参数会将所有依赖库打包进library.zip中，但PySide6的初始化代码会尝试从文件系统路径查找Qt模块，而非zip包内的虚拟路径，导致路径查找失败。

解决方案 #

方案1：禁用单文件打包（推荐） #

修改setup.py，取消bundle_files=1设置（改为bundle_files=3或直接移除该参数），同时明确指定需要打包的PySide6模块，并复制必要的动态库文件到输出目录：

from distutils.core import setup
import py2exe, sys
import os
from PySide6 import __file__ as pyside6_path

sys.argv.append('py2exe')

# 获取PySide6的安装目录
pyside6_dir = os.path.dirname(pyside6_path)

setup(
    options={
        'py2exe': {
            'compressed': True,
            'bundle_files': 3,  # 不打包为单文件，依赖文件将直接放在dist目录
            'packages': ['PySide6'],
            'includes': ['PySide6.QtWidgets', 'PySide6.QtCore', 'PySide6.QtGui'],
            'dll_excludes': ['MSVCP90.dll'],  # 排除不必要的系统DLL
        }
    },
    windows=[{'script': "main.py"}],
    data_files=[
        # 复制PySide6核心DLL到dist根目录
        ('', [os.path.join(pyside6_dir, 'Qt6Core.dll'),
              os.path.join(pyside6_dir, 'Qt6Gui.dll'),
              os.path.join(pyside6_dir, 'Qt6Widgets.dll')]),
        # 复制PySide6必要模块文件到dist/PySide6目录
        ('PySide6', [os.path.join(pyside6_dir, 'Qt6.pyd')])
    ]
)

执行打包命令：

py setup.py py2exe

打包完成后，dist目录下会生成main.exe和对应的依赖文件，直接运行main.exe即可正常启动程序。

方案2：强制PySide6从zip包加载（不推荐） #

如果必须单文件打包，可以通过修改PySide6的初始化逻辑来适配zip路径，但该方法需要修改库文件，稳定性较差，步骤如下：

1. 找到PySide6安装目录下的__init__.py文件
2. 修改_find_all_qt_modules函数，使其支持从zip包内查找路径
3. 重新打包

但由于PySide6版本更新可能导致该方法失效，因此优先推荐方案1。

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