Python项目子目录脚本导入顶层functions模块遇ModuleNotFoundError的解决方法

针对你的项目结构：

project/
├── subdir/
│   ├── __init__.py
│   └── script_to_run.py
├── __init__.py
└── functions.py

最简便的解决方式不需要修改sys.path或者本地安装包，只需要调整运行方式或使用相对导入，分两种场景说明：

1. 从项目根目录运行脚本（推荐） #

这是最省心的方式，不需要修改任何代码。在project目录下执行以下命令：

python -m subdir.script_to_run

此时script_to_run.py可以直接使用绝对导入：

from functions import function_to_import

原理：-m参数会让Python把当前工作目录（也就是项目根目录project）加入模块搜索路径，同时将script_to_run.py当作subdir包的一部分加载，而不是独立的脚本，这样就能直接找到顶层的functions模块。

2. 使用相对导入（需配合包方式运行） #

如果你想在代码里明确表示导入的是上层目录的模块，可以在script_to_run.py中使用相对导入：

from ..functions import function_to_import

但注意：不能直接在subdir目录下运行python script_to_run.py（会报错ValueError: attempted relative import beyond top-level package），必须回到项目根目录，用同样的-m方式运行：

python -m subdir.script_to_run

为什么之前的导入会报错？ #

当你直接运行python subdir/script_to_run.py（根目录下）或者python script_to_run.py（子目录下）时，Python会把脚本所在的subdir目录加入模块搜索路径的最前端，同时将脚本标记为__main__独立模块。这种情况下，顶层的functions.py不在模块搜索路径的有效范围内，或者无法通过包的相对导入规则找到，所以会抛出ModuleNotFoundError。

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