Python模块名称正确却触发ModuleNotFoundError，求助排查

问题场景 #

项目目录结构如下：

sopa/
├── main.py
├── Widgets/
│   ├── __init__.py  # 建议添加，可空
│   ├── Letra.py
│   └── widgets.py

运行根目录下的main.py时，导入Widgets.Letra模块触发错误，报错指向Letra.py中的from widgets import Widget语句，提示找不到widgets模块。

错误原因 #

Python的模块搜索路径以运行脚本所在目录（此处为sopa目录）为起点。Letra.py里直接写from widgets import Widget时，Python会在sopa根目录下查找widgets.py，而非Widgets子目录内的同名文件，因此导致模块找不到。

解决方案 #

方案1：使用相对导入 #

修改Letra.py的导入语句，用相对路径指向同目录的widgets模块：

# Letra.py 修改后的头部代码
from .widgets import Widget

这里的.代表当前模块所在的Widgets目录，Python会正确定位到同目录下的widgets.py。

方案2：使用绝对导入 #

改用完整的包路径导入，确保Python能准确定位到目标模块：

# Letra.py 修改后的头部代码
from Widgets.widgets import Widget

这种方式不受运行路径影响，只要Widgets被识别为合法Python包（目录下存在__init__.py文件）即可正常工作。

额外注意事项 #

• 建议在Widgets目录下添加__init__.py文件（可以是空文件），虽然Python 3.3+支持无该文件的命名空间包，但显式添加能避免多数导入歧义，让目录明确被识别为Python包。

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