自定义Python项目结构下ModuleNotFoundError问题排查

直接运行python3 helloworld/main.py时，Python会将helloworld目录添加到模块搜索路径（sys.path），而非它的父目录（即包含helloworld的项目根目录）。这就导致hello/hello.py中尝试导入helloworld.world.utils时，Python找不到名为helloworld的顶级包。

方法1：用模块模式运行（推荐） #

1. 切换到项目根目录（也就是包含helloworld的那个目录）
2. 执行以下命令：

python3 -m helloworld.main

3. 同时修改main.py的导入语句为绝对导入：

from helloworld.hello.hello import say_hello

或者使用相对导入：

from .hello.hello import say_hello

这种方式会自动将项目根目录加入sys.path，让Python正确识别helloworld作为顶级包，所有导入逻辑都会正常工作。

方法2：临时修改sys.path #

在main.py的最顶部添加以下代码，手动将项目根目录加入模块搜索路径：

import sys
import os
# 获取项目根目录（helloworld的父目录）并添加到sys.path最前面
sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))

修改后，无论你从哪个路径运行python3 helloworld/main.py，都能正常导入helloworld包，原有的导入语句无需修改。

方法3：使用相对导入调整内部包引用 #

修改hello/hello.py中的导入语句为相对导入，基于当前包的位置引用world模块：

from ..world.utils import get_number

这种方式不依赖顶级包名称，仅通过包的层级关系导入，适合项目内部模块间的引用。搭配模块模式运行（方法1）即可正常工作。

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