Python自定义模块导入失败，多目录项目运行报错求助

项目结构 #

src
 |__model
      |___models.py
      |___prepare_data.py
 |__utils.py

问题分析 #

• 在model目录执行python models.py：prepare_data.py找不到utils模块，因为当前目录为model，Python仅在当前目录和系统默认路径搜索模块，utils.py所在的src目录不在搜索范围内。
• 在src目录执行python model/models.py：models.py找不到prepare_data模块，因为直接运行脚本时，model目录不会被自动加入模块搜索路径。

规范解决方法 #

方法1：相对导入 + 模块方式运行 #

1. 给src和model目录都添加空的__init__.py文件，让Python识别为可导入的包。
2. 修改导入语句：
   • models.py中导入prepare_data：

     from . import prepare_data
     

   • prepare_data.py中导入utils：

     from .. import utils
     

3. 运行命令：必须在src目录的上级目录执行（假设src的上级目录为项目根目录）：

   python -m src.model.models
   

   注意：相对导入仅在模块被导入时生效，不能直接运行models.py脚本，必须用-m参数以模块方式启动。

方法2：绝对导入 + 配置PYTHONPATH #

1. 修改所有导入语句为绝对路径：
   • models.py中：

     from src.model import prepare_data
     

   • prepare_data.py中：

     from src import utils
     

2. 配置PYTHONPATH：
   • Linux/macOS：终端执行

     export PYTHONPATH=/实际路径/到/src:$PYTHONPATH
     

   • Windows（CMD）：

     set PYTHONPATH=C:\实际路径\到\src;%PYTHONPATH%
     

   • Windows（PowerShell）：

     $env:PYTHONPATH = "C:\实际路径\到\src;$env:PYTHONPATH"
     

3. 运行方式：配置后可在任意目录运行，例如：

   # 项目根目录下
   python src/model/models.py
   # src目录下
   python model/models.py
   # 模块方式
   python -m src.model.models
   

   也可以在IDE中把src的上级目录设置为项目根目录，IDE会自动将src加入模块搜索路径，无需手动配置环境变量。

临时方法的弊端 #

使用sys.path.append('../')的方式依赖运行时的当前工作目录，一旦切换运行目录就会失效，且不符合Python模块导入的规范，不建议长期使用。

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