子文件夹运行Uvicorn出现ModuleNotFoundError的问题求助

解决方法 #

方法1：直接运行app对象 #

修改main.py中的启动代码，跳过模块路径查找，直接传入当前脚本里的app实例：

if __name__ == '__main__':
    uvicorn.run(app)

执行python subfolder/main.py时，uvicorn会直接加载当前脚本中的FastAPI实例，无需识别模块。

方法2：用模块方式启动脚本 #

在Project目录下执行以下命令，通过Python模块运行方式启动：

python -m subfolder.main

这种方式会自动把Project目录加入Python的模块搜索路径（sys.path），让Python能正常识别subfolder作为合法模块。

方法3：手动添加项目根目录到搜索路径 #

在main.py最开头添加代码，把Project目录手动加入sys.path：

import sys
import os
# 获取当前脚本绝对路径，向上一级定位到Project目录
project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.append(project_root)

之后执行python subfolder/main.py就能正常识别subfolder模块，不过这种方法不如前两种简洁。

原因分析 #

1. PyCharm运行正常的原因：PyCharm默认会把项目根目录（Project）添加到Python的sys.path中，启动时Python能找到subfolder模块，uvicorn.run('subfolder.main:app')可以正常解析。
2. 命令行报错的原因：执行python subfolder/main.py时，Python只会把main.py所在的Subfolder目录加入sys.path，而非Project目录。此时用subfolder.main的模块路径指定app，Python在sys.path里找不到subfolder模块，所以抛出ModuleNotFoundError。
3. 添加__init__.py无效的原因：__init__.py的作用是把目录标记为可导入的Python模块，但问题核心是Project目录不在sys.path里，就算Subfolder是模块，Python也找不到它的父目录下的这个模块，所以加了也没用。

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