如何导入同级目录下的Python模块？包结构正确仍报ModuleNotFound错误如何解决

• Python导入模块时，只会搜索当前工作目录、系统PYTHONPATH环境变量包含的目录、Python安装自带的标准库目录、第三方包的site-packages目录。你出现ModuleNotFound错误的核心原因是项目根目录/python-tools不在Python的模块搜索路径里：
  • 如果你直接在/python-tools/module_a目录下执行python module_a.py，当前工作目录是/python-tools/module_a，自然找不到上层的common包
  • 你说的符合Python包规范是对的，但规范成立的前提是你把项目根目录作为包的父目录来使用，而不是直接运行子目录里的单个脚本

• 方案1：以模块方式运行脚本 #

  不要直接运行单文件，切换到/python-tools的上级目录，执行如下命令即可：

  python -m python-tools.module_a.module_a
  

  用-m参数运行时，Python会自动把当前工作目录加入模块搜索路径，就能正常识别common包。

• 方案2：安装为开发模式包（推荐长期项目使用） #

  在/python-tools的上级目录下执行：

  pip install -e .
  

  这个命令会把你的项目以软链接的形式安装到Python的site-packages目录，全局都可以识别python-tools下的所有包，你修改项目代码也不需要重新安装，完全符合Python包的使用规范。

• 方案3：IDE中配置源码根目录 #

  如果你用PyCharm/VS Code等IDE开发，直接把/python-tools目录标记为源码根目录即可：

  • PyCharm：右键/python-tools目录 → 选择「Mark Directory as」→ 「Sources Root」
  • VS Code：在项目的.vscode/settings.json中添加配置：

    {
      "python.analysis.extraPaths": ["/path/to/your/python-tools"]
    }
    

  IDE运行代码时会自动把标记的源码根目录加入模块搜索路径，无需额外操作。

注意：

1. 不要尝试在作为入口运行的module_a.py/module_b.py里用相对导入（比如from ..common.common import CommonClass），这种写法会直接报「attempted relative import in non-package」错误，相对导入只能在包内部被其他模块导入时使用，不能用于入口脚本。
2. 若使用-m参数运行时因为目录名带横杠报错，可将/python-tools重命名为符合Python包命名规范的python_tools（用下划线替代横杠）即可。

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