uvicorn Error loading ASGI app: Could not import module (tested)

ERROR: Error loading ASGI app. Could not import module "main" means uvicorn could not import the module named before the colon from the directory you ran it in. Its sibling Attribute "app" not found in module means the module loaded but the variable after the colon has a different name.

Layout: proj/src/main.py (no __init__.py in src/) containing:

from fastapi import FastAPI
api = FastAPI()          # note: named "api", not "app"

1. The three messages and what each means

cd /w/proj
echo '$ uvicorn main:app            (from proj/, main.py is in src/)'; uvicorn main:app 2>&1 | tail -1
echo '$ uvicorn src.main:app'; uvicorn src.main:app 2>&1 | tail -1
echo '$ uvicorn src.main:api        (right module and name)'; timeout 3 uvicorn src.main:api --port 8000 > /tmp/u.log 2>&1; grep -m1 -E "Started server|ERROR" /tmp/u.log
echo '$ uvicorn main:api --app-dir src'; timeout 3 uvicorn main:api --app-dir src --port 8000 > /tmp/u.log 2>&1; grep -m1 -E "Started server|ERROR" /tmp/u.log
echo '$ uvicorn main.py:api'; cd src; uvicorn main.py:api 2>&1 | tail -1

Output:

$ uvicorn main:app            (from proj/, main.py is in src/)
ERROR:    Error loading ASGI app. Could not import module "main".
$ uvicorn src.main:app
ERROR:    Error loading ASGI app. Attribute "app" not found in module "src.main".
$ uvicorn src.main:api        (right module and name)
INFO:     Started server process [16]
$ uvicorn main:api --app-dir src
INFO:     Started server process [20]
$ uvicorn main.py:api
ERROR:    Error loading ASGI app. Could not import module "main.py".

The argument is module.path:variable, imported like a Python import from the directory you run uvicorn in:

• Could not import module "main": there is no main.py in the current directory (or on sys.path). Run from the right directory, use the dotted path (src.main), or pass --app-dir src.
• Attribute "app" not found in module: the module imported fine, but the variable has another name. Use the name you assigned the FastAPI() object to (here api).
• Could not import module "main.py": a file name is not a module name. Drop the .py; use dots, not slashes, for folders.

2. When the real error is inside your app

proj2/main.py imports a package that is not installed:

from fastapi import FastAPI
import databasez_missing   # a typo / uninstalled package inside the app
app = FastAPI()

cd /w/proj2
echo '$ uvicorn main:app'; uvicorn main:app 2>&1 | tail -3

Output:

$ uvicorn main:app
    import databasez_missing   # a typo / uninstalled package inside the app
    ^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'databasez_missing'

If your module itself fails to import (missing package, typo, syntax error), uvicorn shows the full traceback, and the last line is the real problem, not "Error loading ASGI app". A ModuleNotFoundError here usually means the package is not installed in the environment uvicorn runs from: check with which uvicorn / python -m uvicorn from the activated venv.

Checklist

• cd to the directory that contains the module (or its top package), then run uvicorn package.module:variable.
• In Docker, check WORKDIR matches, or use --app-dir.
• The variable name after the colon matches the code exactly.
• Use python -m uvicorn ... to be sure the same interpreter that has your packages runs the app.

Related: FastAPI 422 Unprocessable Entity.

Written with AI assistance. Measured on 2026-10-23 with uvicorn 0.54.0, FastAPI 0.161.1 and Python 3.14.7 (python:3-alpine in Docker). Each block was run verbatim and the output pasted unedited. PlainHeaders is our extension; Python, FastAPI and uvicorn are free.