使用pip install -e .时Python项目内部依赖导入异常原因咨询

项目结构 #

└─mris
    ├─mris.egg-info
    ├─seggms
    │  ├─training
    │  │  └─run_training.py 
    ├─utilities
    │  └─config.py (包含adjust_config函数)

所有目录均为Python包结构，已通过pip install -e .完成可编辑模式安装，pyproject.toml核心配置如下：

[tool.setuptools.packages.find]
where = ["mris"]
include = ["mris", "mris.*"]

导入行为差异 #

在mris/seggms/training/run_training.py中调用adjust_config()函数时，两种导入方式表现不一致：

1. 绝对导入方式：from mris.utilities.config import adjust_config
   • PyCharm内运行正常
   • Linux命令行直接执行脚本时触发错误：

     File "/home/ubuntu/workspace/MSM-Synth/mris/seggms/training/run_training.py", line 1, in <module>
         from mris.utilities.config import adjust_config
     ModuleNotFoundError: No module named 'mris'
     

2. 相对路径式导入：from utilities.config import adjust_config
   • Linux命令行执行时正常

另外，直接启动Python解释器执行import mris可正常运行。

1. PyCharm的路径自动处理 #

PyCharm默认会将项目根目录（即包含mris文件夹的上级目录）添加到Python的sys.path中，因此绝对导入from mris.utilities...可以被正确解析。

2. 命令行直接执行脚本的路径优先级 #

当你在命令行直接运行python mris/seggms/training/run_training.py时，Python会将脚本所在的目录（mris/seggms/training/）插入到sys.path的最前端，而非项目根目录。此时mris包不在sys.path的搜索范围内，导致绝对导入失败。

而from utilities.config...能生效，是因为脚本所在目录的祖父目录正是mris包的根目录，此时Python会从该目录开始搜索模块，刚好匹配到utilities包。这种情况属于依赖当前工作目录的"巧合"，并非标准的包导入方式。

3. 直接启动解释器的正常性 #

直接启动Python解释器时，你的工作目录通常是项目根目录，加上pip install -e .已将mris包以软链接形式注册到Python的site-packages中，因此import mris可以被正确找到。

• 推荐方案：始终使用绝对导入，同时通过python -m mris.seggms.training.run_training的方式执行脚本（-m参数会将项目根目录加入sys.path，符合Python包的导入规范）；或者在pyproject.toml中配置[project.scripts]，生成可直接调用的控制台脚本。
• 临时方案：如果必须直接执行脚本，可在脚本开头手动将项目根目录加入sys.path：

  import sys
  from pathlib import Path
  # 将项目根目录（mris文件夹的上级目录）加入sys.path
  sys.path.append(str(Path(__file__).resolve().parent.parent.parent))
  

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