从父目录导入模块时出现ImportError的原因及解决方法

错误原因 #

直接运行main/script.py时，Python将该文件视为独立脚本，而非包结构的一部分。此时Python的模块搜索路径仅包含main目录和系统默认路径，无法识别上层的sample目录为父包，因此相对导入from ..utils import say_hi找不到对应的父包，触发ImportError。

解决方法 #

方法1：以包模块形式运行 #

切换到项目根目录sample，在终端执行：

python -m main.script

这种方式会让Python将sample作为包的根目录，正确解析相对导入的层级关系。

方法2：改用绝对导入 #

修改script.py的导入语句为绝对导入：

from utils import say_hi
say_hi()

同时需确保sample目录在Python的模块搜索路径中：

• 在VSCode中直接打开sample目录作为工作区，Python会自动将其加入sys.path；
• 或者手动在script.py开头添加路径配置：

  import sys
  from pathlib import Path
  # 将项目根目录添加到模块搜索路径
  sys.path.append(str(Path(__file__).parent.parent))
  

方法3：配置VSCode运行参数 #

在VSCode的.vscode/launch.json中添加以下运行配置，指定以模块方式运行并设置正确的工作目录：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Run Script as Module",
            "type": "python",
            "request": "launch",
            "module": "main.script",
            "cwd": "${workspaceFolder}/sample"
        }
    ]
}

之后选择该配置运行脚本即可。

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