Python直接运行子包脚本触发ModuleNotFoundError相对导入问题求解

核心原理 #

Python的模块导入逻辑完全依赖sys.path中的搜索路径列表，导入模块时会按顺序遍历sys.path中的路径查找匹配的模块/包，两个运行场景的差异直接导致了导入结果不同：

• 直接运行python3 first_package/a.py时：Python会自动将a.py所在的目录myproject/first_package添加到sys.path的最靠前位置，此时搜索路径下只存在first_package内的文件，找不到位于myproject根目录下的second_package，因此抛出ModuleNotFoundError。同时直接运行的脚本的__name__属性会被设为__main__，不会被识别为first_package包的组成部分，即使用相对导入也会报错。
• 运行根目录下的main.py时：Python会将main.py所在的myproject根目录添加到sys.path最靠前位置，此时first_package和second_package都在搜索路径覆盖范围内，因此跨包导入可以正常执行。

可行解决方案 #

• 方案1：使用-m参数以模块形式运行子包内的脚本，需要在项目根目录下执行命令：

  python3 -m first_package.a
  python3 -m first_package.b
  

  该参数会将当前工作目录（即项目根目录）加入sys.path，同时将脚本识别为包的子模块，导入逻辑完全和在main中导入一致。
• 方案2：统一项目执行入口，所有需要直接运行的逻辑都放在根目录的入口文件（如main.py）中，子包内的模块仅保留被调用的功能代码，不写直接执行的逻辑，这是目前企业级项目的通用规范，能完全避免导入路径混乱问题。
• 方案3（应急使用，不推荐长期落地）：在子包模块的最开头手动将项目根目录加入搜索路径：

  import sys
  from pathlib import Path
  # 两次parent就是从first_package/a.py向上跳到myproject根目录
  sys.path.append(str(Path(__file__).parent.parent.resolve()))
  

内容的提问来源于stack exchange，提问作者Jan Janáček