如何让Python项目从根目录加载模块？解决导入报错问题

首先得理清问题根源：当你直接在命令行运行python scripts/parser.py（或从项目根目录执行python Analysis/src/notebooks/scripts/parser.py）时，Python会把当前工作目录加入sys.path，但你的scripts目录位于$MY_PROJECT/Analysis/src/notebooks/下，不在默认的sys.path范围内，所以parser.py里尝试导入scripts模块时会抛出ModuleNotFoundError。而Notebook里你手动把scripts目录加入了sys.path，所以能正常运行，但这种方式无法通用到命令行场景。

下面给出几种从简单到进阶的解决方案：

方案1：统一添加项目根目录到sys.path（快速适配） #

这种方法不需要修改项目结构，只需要在Notebook和脚本中自动计算并添加项目根目录，然后使用绝对导入。

针对Notebook： #

替换你原来的sys.path修改代码，改为计算项目根目录：

import os
import sys

# 从Notebook所在目录（$MY_PROJECT/Analysis/src/notebooks）往上三级得到项目根
project_root = os.path.abspath(os.path.join(os.getcwd(), "../../../../"))
if project_root not in sys.path:
    sys.path.append(project_root)

# 从项目根开始的绝对导入
from Analysis.src.notebooks.scripts.parser import load_static_data

针对parser.py脚本： #

在脚本开头添加同样的逻辑，自动识别项目根：

import os
import sys

# 从当前脚本所在目录（$MY_PROJECT/Analysis/src/notebooks/scripts）往上四级得到项目根
project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../../"))
if project_root not in sys.path:
    sys.path.insert(0, project_root)

# 绝对导入
from Analysis.src.notebooks.scripts.parser import load_static_data

# 你的__main__逻辑
if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("input1")
    parser.add_argument("output_folder")
    args = parser.parse_args()
    load_static_data(args.input1, args.output_folder)

这样不管你在哪个目录运行脚本，都能正确导入模块。

方案2：设置PYTHONPATH环境变量（无需修改代码） #

通过设置PYTHONPATH，让Python自动把项目根目录加入sys.path，这样所有导入都可以基于项目根，不需要在代码里手动修改sys.path。

Linux/macOS终端： #

# 临时设置（仅当前会话有效）
export PYTHONPATH="$MY_PROJECT:$PYTHONPATH"

# 永久设置（添加到~/.bashrc或~/.zshrc）
echo 'export PYTHONPATH="$MY_PROJECT:$PYTHONPATH"' >> ~/.bashrc
source ~/.bashrc

Windows命令行： #

# 临时设置
set PYTHONPATH=%MY_PROJECT%;%PYTHONPATH%

# 永久设置（通过系统属性-环境变量添加）

Windows PowerShell： #

# 临时设置
$env:PYTHONPATH = "$MY_PROJECT;$env:PYTHONPATH"

# 永久设置
[Environment]::SetEnvironmentVariable("PYTHONPATH", "$MY_PROJECT;$env:PYTHONPATH", "User")

设置完成后，不管是Notebook还是命令行，都可以直接用绝对导入：

• Notebook里：from Analysis.src.notebooks.scripts.parser import load_static_data
• parser.py里：同样的导入语句，无需任何sys.path修改

方案3：将项目安装为可编辑包（长期项目推荐） #

如果这是一个需要长期维护的项目，推荐把它安装为Python的可编辑包，这样Python会自动识别项目结构，导入更简洁，也符合Python包管理规范。

步骤如下：

1. 在项目根目录$MY_PROJECT下创建pyproject.toml文件：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-analysis-project"
version = "0.1.0"
packages = ["notebooks.scripts"]
package_dir = {"": "Analysis/src"}

这里把Analysis/src作为包的根目录，notebooks.scripts对应路径$MY_PROJECT/Analysis/src/notebooks/scripts。

2. 在项目根目录运行命令安装为可编辑模式：

pip install -e .

安装完成后，你可以用更简洁的导入路径：

• Notebook里：from notebooks.scripts.parser import load_static_data
• parser.py里：同样的导入语句，无需任何sys.path修改

额外建议：优化项目结构（可选） #

如果可以调整，建议把脚本和Notebook分开，采用更常规的Python项目布局：

$MY_PROJECT/
├── src/
│   └── scripts/
│       ├── __init__.py
│       └── parser.py
├── notebooks/
│   └── analysis.ipynb
└── pyproject.toml

这样导入路径会更简洁（from scripts.parser import load_static_data），也更便于团队协作和维护。

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