在Bash终端执行Python项目遇ModuleNotFoundError问题求助

问题原因 #

IDE会自动将项目根目录加入Python的模块搜索路径（sys.path），但直接在终端执行python src/main.py时，Python仅会把src/目录加入搜索路径，导致无法识别src作为顶层模块。

解决方法 #

1. 以模块方式运行（推荐） #

切换到项目根目录，使用-m参数运行模块：

cd ~/bentoml-airquality
python -m src.main

-m参数会自动将当前目录（项目根）加入sys.path，让Python识别src为合法模块。

2. 临时设置PYTHONPATH环境变量 #

在执行脚本前，将项目根目录添加到PYTHONPATH：

# Linux/macOS 临时生效
PYTHONPATH=~/bentoml-airquality python src/main.py

如果需要长期生效，可以把export PYTHONPATH=~/bentoml-airquality:$PYTHONPATH加入你的shell配置文件（如~/.bashrc或~/.zshrc）。

3. 在脚本中手动添加路径 #

在src/main.py的最顶部（所有导入语句之前）添加以下代码：

import sys
import os
# 将项目根目录（src的父目录）加入搜索路径
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

这样脚本执行时会自动把项目根目录加入sys.path，无需依赖环境变量。

4. 用setup.py规范项目结构（适合长期维护） #

在项目根目录创建setup.py文件：

from setuptools import setup, find_packages

setup(
    name="bentoml-airquality",
    version="0.1.0",
    packages=find_packages(),
)

然后以可编辑模式安装项目：

pip install -e .

安装后，你可以在任意目录通过python -m src.main运行脚本，或直接执行src/main.py。

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