FastAPI相对导入报错：ImportError: attempted relative import with no known parent package

错误原因 #

直接把main.py作为独立脚本运行时，Python不会将其识别为某个包的子模块，而是当作顶层模块处理，此时带.的相对导入语法会失效——因为找不到对应的"父包"。

解决方案 #

方案1：用模块方式启动（推荐，符合Python包规范） #

1. 补全项目包结构：确保每个目录下都有空的__init__.py文件，让Python识别为合法包，你的项目结构应该类似这样：

Fast-api/
├── src/
│   ├── __init__.py
│   ├── main.py
│   ├── routers/
│   │   ├── __init__.py
│   │   └── fileupload.py
│   ├── posts/
│   │   ├── __init__.py
│   │   ├── utils.py
│   │   └── schemas.py
│   └── startup.py

2. 从项目根目录启动：
   • 方式一：用Python模块命令运行

     cd /home/Fast-api
     python -m src.main
     

     同时修改main.py里的uvicorn启动参数：

     if __name__ == "__main__":
         uvicorn.run("src.main:app", host="0.0.0.0", port=5000, reload=True)
     

   • 方式二：直接用uvicorn命令启动（更简洁）

     cd /home/Fast-api
     uvicorn src.main:app --host 0.0.0.0 --port 5000 --reload
     

     这种方式下可以删掉main.py里的if __name__ == "__main__"代码块，直接由uvicorn管理启动流程。

方案2：改用绝对导入（适合不想调整启动方式的场景） #

把所有相对导入语句改为基于项目根目录的绝对导入：

• main.py中的导入修改为：

  from src.routers import fileupload
  from src.startup import startup_function
  

• fileupload.py中的导入修改为：

  from src.posts.utils import get_file_upload, pipeline
  from src.posts.schemas import FileUpload
  from src.startup import db
  

然后在main.py的最开头添加代码，将项目根目录加入Python的路径搜索列表：

import sys
from pathlib import Path
# 把项目根目录（/home/Fast-api）加入sys.path
sys.path.append(str(Path(__file__).parent.parent))

修改完成后就可以直接运行python src/main.py了。

关键提醒 #

• 相对导入仅适用于包内部的模块之间，不能在顶层脚本中使用。
• 显式添加__init__.py能确保Python稳定识别包结构（Python 3.3+支持无该文件的命名空间包，但显式添加更稳妥）。

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