Python项目模块缺失问题：直接运行chatbox.py为何报ModuleNotFoundError？

项目结构 #

📁 renny
|
|____📁 app
     |____📄 __init__.py
     |____📄 chatbox.py
|
|____📁 utils
     |____📄 __init__.py
     |____📄 wids.py
|
|____📄 main.py

问题描述 #

• main.py导入chatbox.py，chatbox.py导入wids.py，运行main.py完全正常。
• 但直接运行chatbox.py时，会抛出错误：ModuleNotFoundError: No module named 'utils'。
• 尝试把utils文件夹移到app目录下，此时运行main.py反而出现相同的导入错误，不符合预期。
• 试过重启VSCode、换电脑、用/不用虚拟环境、重构文件夹结构，问题都没解决。
• 这是个小型项目，不想创建setup.py或做成可安装包，只想搞懂问题的根源。

当前sys.path内容 #

['c:\\Benaj\\Desktop\\renny\\app',
'C:\\Users\\Benaj\\AppData\\Local\\Programs\\Python\\Python310\\python310.zip',
'C:\\Users\\Benaj\\AppData\\Local\\Programs\\Python\\Python310\\DLLs',
'C:\\Users\\Benaj\\AppData\\Local\\Programs\\Python\\Python310\\lib',
'C:\\Users\\Benaj\\AppData\\Local\\Programs\\Python\\Python310',
'c:\\Benaj\\Desktop\\renny\\env',
'c:\\Benaj\\Desktop\\renny\\env\\lib\\site-packages']

问题根源与解答 #

为什么会报错？ #

Python找模块全靠sys.path这个列表：

• 运行main.py时，Python会自动把main.py所在的项目根目录（c:\\Benaj\\Desktop\\renny）加入sys.path，utils是根目录下的同级包，自然能被找到。
• 直接运行chatbox.py时，Python自动加入sys.path的是chatbox.py所在的app目录（c:\\Benaj\\Desktop\\renny\\app），utils在它的上一级，不在sys.path里，所以找不到。

sys.path需要包含utils文件夹吗？ #

不需要。只要sys.path里包含utils的父目录（也就是项目根目录c:\\Benaj\\Desktop\\renny），Python就能识别到utils这个包。

小型项目的快速解决方法 #

方法1：在chatbox.py里手动添加项目根目录到sys.path

在chatbox.py的最开头加这段代码：

import sys
import os
# 获取项目根目录的绝对路径
project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
if project_root not in sys.path:
    sys.path.append(project_root)

这样不管从哪里运行chatbox.py，都能正确找到utils模块。

方法2：从项目根目录用模块方式运行

打开终端，切换到renny文件夹，执行：

python -m app.chatbox

这种方式会自动把项目根目录加入sys.path，也能避免导入错误。

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