导入特定模块时出现ModuleNotFoundError的问题排查与解决

核心原因 #

直接运行python ./main.py时，Python的模块搜索路径（sys.path）默认以执行命令的当前目录为准，而非main.py所在的src目录。比如你在repository目录下执行命令，sys.path里没有src路径，自然找不到a.py；而进入src目录打开Python shell时，sys.path包含当前的src目录，所以能正常导入b.py、c.py。

另外需排查：a.py的文件名是否存在拼写错误、特殊字符，或者是否与Python标准库模块重名（比如命名为math.py会和标准库冲突）。

解决办法 #

方法1：切换到src目录运行 #

cd src
python main.py

此时sys.path会自动包含src目录，模块导入逻辑正常。

方法2：在main.py中手动添加搜索路径 #

在main.py的最开头添加以下代码，强制将src目录加入模块搜索路径：

import sys
from pathlib import Path

# 获取当前脚本所在的src目录
src_directory = Path(__file__).resolve().parent
# 添加到sys.path
sys.path.append(str(src_directory))

这种方式无论从哪个目录运行main.py，都能找到src下的模块。

方法3：将src作为Python包运行（推荐） #

1. 在src目录下创建空文件__init__.py，将src标记为Python包：

repository
  /src
    /__init__.py
    /main.py
    /a.py
    /b.py
    /c.py

2. 在repository目录下执行以下命令运行程序：

python -m src.main

这种方式符合Python的包结构规范，能避免路径相关的导入问题。

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