使用PyInstaller打包Python项目遇ModuleNotFoundError问题求助

项目结构 #

src/
├── __init__.py
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── main.spec
│   └── version.rc
└── lib/
    ├── __init__.py
    ├── core/
    │   ├── __init__.py
    │   └── core_test.py
    └── service/
        ├── __init__.py
        └── service_test.py

main.py代码 #

from src.lib.service import service_tst
from src.lib.core import core_tst

service_tst.do_something()
core_tst.do_something()

main.spec文件内容 #

block_cipher = None
a = Analysis(['main.py'],
         pathex=[],
         binaries=[],
         datas=[],
         hiddenimports=[],
         hookspath=[],
         hooksconfig={},
         runtime_hooks=[],
         excludes=[],
         win_no_prefer_redirects=False,
         win_private_assemblies=False,
         cipher=block_cipher,
         noarchive=False)
pyz = PYZ(a.pure, a.zipped_data,
         cipher=block_cipher)

exe = EXE(pyz,
      a.scripts, 
      a.binaries,
      a.zipfiles,
      a.datas,
      [],
      name='main',
      debug=False,
      bootloader_ignore_signals=False,
      strip=False,
      upx=True,
      upx_exclude=[],
      runtime_tmpdir=None,
      console=True,
      disable_windowed_traceback=False,
      target_arch=None,
      codesign_identity=None,
      entitlements_file=None,
      icon='',
      version='version.rc')

执行报错 #

ModuleNotFoundError: No module named 'src'

已尝试的解决方法 #

• 将src加入hiddenimports，报错：ModuleNotFoundError: No module named 'src.lib'
• 将src和src.lib加入hiddenimports，仍报错：ModuleNotFoundError: No module named 'src.lib'
• 使用collect_submodules('src')获取隐藏导入，依旧报错：ModuleNotFoundError: No module named 'src.lib'

解决方案 #

核心问题是PyInstaller的模块搜索路径未包含项目根目录（即src所在的父目录），导致无法识别src作为顶层模块。只需调整spec文件中的pathex参数即可解决：

修改main.spec的Analysis部分 #

import os
block_cipher = None
# 获取main.py所在目录的上级目录（即项目根目录，src的父目录）
project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
a = Analysis(['main.py'],
         pathex=[project_root],  # 加入项目根目录
         binaries=[],
         datas=[],
         hiddenimports=[],
         hookspath=[],
         hooksconfig={},
         runtime_hooks=[],
         excludes=[],
         win_no_prefer_redirects=False,
         win_private_assemblies=False,
         cipher=block_cipher,
         noarchive=False)

原理说明 #

PyInstaller默认仅从当前脚本所在目录和系统Python路径查找模块。由于main.py位于src/app下，直接打包时无法向上找到src模块。将项目根目录加入pathex后，PyInstaller会自动扫描src下的所有子模块，无需手动添加大量hiddenimports。

替代方案（可选） #

打包前先将项目根目录添加到PYTHONPATH环境变量：

# Windows
set PYTHONPATH=.\..;%PYTHONPATH%
# Linux/macOS
export PYTHONPATH=./..:$PYTHONPATH

之后再运行pyinstaller main.spec，无需修改spec文件的pathex。

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