Python如何正确导入使用包内类 解决包内模块导入ModuleNotFoundError问题

报错原因 #

你遇到的报错本质是Python模块搜索路径的问题：当你直接运行python foo.py时，Python会自动将foo.py所在的test_lib目录加入模块搜索路径sys.path，而项目根目录不在搜索路径里，所以找不到顶层包test_lib，也就无法解析from test_lib.bar import bar这个导入语句。而运行main.py的时候，Python会把项目根目录加入sys.path，所以能正常找到test_lib包。

推荐解决方案 #

方案1：使用相对导入+模块运行命令（最符合Python包规范） #

首先修改foo.py的导入语句为相对导入，适配包内调用场景：

# 把原来的 from test_lib.bar import bar 改成下面的写法
from .bar import bar

这种写法下运行main.py完全正常，如果需要单独调试foo.py的功能，不要直接运行python foo.py，切换到项目根目录后使用模块方式运行即可：

python -m test_lib.foo

Python会自动将当前根目录加入搜索路径，能正确识别test_lib包。

方案2：双场景兼容写法 #

如果确实需要同时支持「直接运行foo.py」和「作为包被main调用」两种场景，可以在foo.py开头增加路径兼容逻辑：

import sys
from pathlib import Path

# 直接运行时自动把项目根目录加入搜索路径
if __name__ == '__main__':
    sys.path.append(str(Path(__file__).parent.parent.resolve()))

from test_lib.bar import bar

修改后两种运行方式都可以正常执行，不需要额外调整运行命令。

方案3：临时配置PYTHONPATH环境变量（适合本地调试） #

开发阶段可以临时将项目根目录加入PYTHONPATH环境变量，一劳永逸解决路径搜索问题：

• Windows cmd下执行：set PYTHONPATH=你的项目根目录绝对路径
• Linux/Mac终端下执行：export PYTHONPATH=你的项目根目录绝对路径
  配置完成后无论运行main.py还是直接运行foo.py都不会出现找不到包的问题。

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