FastAPI Todo全栈后端应用出现ModuleNotFoundError问题求助

项目环境与结构 #

基于Windows 10开发FastAPI Todo全栈应用后端，项目结构如下：

.backend
|   .dockerignore
|   .env
|   .gitignore
|   Dockerfile
|   requirements.txt
|
\---app
    |   database.py
    |   main.py
    |   __init__.py
    |
    +---models
    |       auth.py
    |       todo.py
    |       __init__.py
    |
    +---routes
    |       auth.py
    |       todo.py
    |       __init__.py
    |
    \---services
            auth.py
            todo.py
            __init__.py

app/main.py代码：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from app.routes import todo


app = FastAPI(title="Todo")

app.include_router(todo.router)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

报错情况 #

1. 在backend目录执行uvicorn app.main:app --reload时，报错：

Traceback (most recent call last):
  File "C:\Users\mabes\python310\lib\multiprocessing\process.py", line 314, in _bootstrap
    self.run()
  File "C:\Users\mabes\python310\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\_subprocess.py", line 76, in subprocess_started     
    target(sockets=sockets)
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\server.py", line 61, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "C:\Users\mabes\python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Users\mabes\python310\lib\asyncio\base_events.py", line 649, in run_until_complete
    return future.result()
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\server.py", line 68, in serve
    config.load()
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\config.py", line 467, in load
    self.loaded_app = import_from_string(self.app)
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\importer.py", line 24, in import_from_string        
    raise exc from None
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\importer.py", line 21, in import_from_string        
    module = importlib.import_module(module_str)
  File "C:\Users\mabes\python310\lib\importlib\__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\app\main.py", line 4, in <module>
    from app.routes import todo
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\app\routes\todo.py", line 4, in <module>
    from models.todo import Todo, TodoCreate, TodoUpdate
ModuleNotFoundError: No module named 'models'

2. 在backend/app目录执行uvicorn main:app --reload时，报错：

Traceback (most recent call last):
  File "C:\Users\mabes\python310\lib\multiprocessing\process.py", line 314, in _bootstrap
    self.run()
  File "C:\Users\mabes\python310\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\_subprocess.py", line 76, in subprocess_started     
    target(sockets=sockets)
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\server.py", line 61, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "C:\Users\mabes\python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Users\mabes\python310\lib\asyncio\base_events.py", line 649, in run_until_complete
    return future.result()
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\server.py", line 68, in serve
    config.load()
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\config.py", line 467, in load
    self.loaded_app = import_from_string(self.app)
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\importer.py", line 24, in import_from_string        
    raise exc from None
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\venv\lib\site-packages\uvicorn\importer.py", line 21, in import_from_string        
    module = importlib.import_module(module_str)
  File "C:\Users\mabes\python310\lib\importlib\__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "C:\Users\mabes\Desktop\todo-fullstack\backend\app\main.py", line 4, in <module>
    from app.routes import todo
ModuleNotFoundError: No module named 'app'

已尝试执行set PYTHONPATH=$PWD但无效，寻求解决方法。

解决方法 #

1. 修正模块导入路径 #

核心问题是app/routes/todo.py中的导入路径错误，需改成以下两种方式之一：

• 绝对导入（推荐，适配项目根目录运行）：

  from app.models.todo import Todo, TodoCreate, TodoUpdate
  

• 相对导入（适合同级目录模块引用）：

  from ..models.todo import Todo, TodoCreate, TodoUpdate
  

同时确保main.py中的导入保持绝对路径：from app.routes import todo，避免在子目录运行时出现路径问题。

2. 正确设置Windows环境下的PYTHONPATH #

Windows的环境变量设置命令与Linux不同，需在backend目录下执行对应命令：

• 若使用CMD：

  set PYTHONPATH=%cd%
  

• 若使用PowerShell：

  $env:PYTHONPATH = Get-Location
  

设置完成后再运行uvicorn app.main:app --reload

3. 统一运行方式 #

始终在backend目录下执行启动命令：

uvicorn app.main:app --reload

这种方式下，Python会自动将backend目录识别为包根目录，结合绝对导入路径，能彻底避免大部分模块导入错误。

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