Skip to main content

How to Resolve Python "Error loading ASGI app. Could not import module '...'"

When launching a FastAPI application using an ASGI server like Uvicorn, a common startup error is Error loading ASGI app. Could not import module 'your_module_name' (e.g., main). This error indicates that Uvicorn, when trying to find and load your FastAPI application object, was unable to locate the specified Python file (.py) based on the path provided and the current working directory.

This guide explains the common causes of this import failure and provides clear, step-by-step solutions to get your FastAPI app running.

Understanding the Error: Uvicorn and Module Imports​

ASGI servers like Uvicorn need to import your Python code to find the actual FastAPI application instance (the ASGI callable) that they will run. Python's import system relies heavily on the Current Working Directory (CWD) – the directory your terminal is currently focused on when you run the uvicorn command – and the specified module path. If Uvicorn cannot find the Python file based on these factors, it raises the "Could not import module" error.

The Uvicorn Command Structure (module:app)​

The standard command format is uvicorn main:app --reload:

  • main: This refers to the Python file main.py. Do not include the .py extension here. If your file is inside a directory (package), you use dot notation (e.g., src.main).
  • :: Separator.
  • app: This refers to the Python variable inside main.py that holds your FastAPI instance (usually created via app = FastAPI()).
  • --reload: An optional flag for development that automatically restarts the server when code changes are detected.

Cause 1: Incorrect Current Working Directory​

This is the most frequent cause. You are running the uvicorn command from a directory where the specified module path (e.g., main) doesn't make sense relative to that location.

Example Scenario:

Your project structure is:

my_fastapi_project/
├── venv/
└── src/
    └── main.py  <-- Contains 'app = FastAPI()'

If your terminal's CWD is my_fastapi_project/ and you run uvicorn main:app, Uvicorn looks for main.py directly inside my_fastapi_project/. It won't find it because it's inside the src/ subdirectory, leading to the error.

Solution 1: Run Uvicorn from the Correct Directory (cd)​

Navigate your terminal into the directory containing the Python file before running uvicorn.

# Navigate to the project root (example)
cd path/to/my_fastapi_project

# Navigate INTO the directory containing main.py
cd src

# Now your CWD is my_fastapi_project/src/
# Run uvicorn using the simple module name
uvicorn main:app --reload --port 8500

By running uvicorn from the src directory, the simple path main correctly resolves to main.py within that directory.

Cause 2: Incorrect Module Path Specification​

If you don't want to cd into the directory containing your app file, you need to tell Uvicorn how to find it relative to your CWD using Python's dot notation for modules/packages. Crucially, use dots (.), not slashes (/ or \).

Example Scenario:

Using the same structure as before:

my_fastapi_project/  <-- Terminal CWD is here
├── venv/
└── src/
    └── main.py

Solution 2: Specify the Correct Module Path (Dot Notation)​

Run the command from the project root (my_fastapi_project/) but specify the path using dots.

# Terminal is in my_fastapi_project/

# Incorrect path using slash:
# uvicorn src/main:app --reload  # WRONG!

# ✅ Correct path using dot notation:
uvicorn src.main:app --reload --port 8500
  • src.main: Tells Uvicorn to look for a package/directory named src in the CWD, and then import the main module ( main.py) from within src.

Cause 3: Incorrect ASGI Application Object Name​

The part after the colon (:) in the Uvicorn command must exactly match the variable name you assigned to your FastAPI() instance in your Python file.

Example Scenario:

# main.py
from fastapi import FastAPI

# Variable name is 'my_api_instance', NOT 'app'
my_api_instance = FastAPI()

@my_api_instance.get("/")
def root():
    return {"message": "Hello"}

If you run uvicorn main:app, it will fail because there is no object named app in main.py.

Solution 3: Verify the Application Object Name (:app)​

Ensure the name after the colon in the command matches the variable name in your Python code.

# Correct command for the code above
uvicorn main:my_api_instance --reload

Conventionally, app is used, but you must be consistent.

Cause 4: Syntax Errors or Import Errors Within Your Module​

If your main.py file (or any file it imports) contains a Python syntax error or fails on an import (ModuleNotFoundError for another library), Python cannot successfully execute and load the module. Uvicorn's attempt to import it will fail, sometimes resulting in the "Could not import module" error.

Solution 4: Check Your Application Code (python your_module.py)​

Try running your main application file directly with Python to catch any underlying errors:

# Navigate to the directory containing main.py
cd path/to/my_fastapi_project/src

# Run the file directly
python main.py

If this command shows any SyntaxError, ImportError, NameError, etc., fix those Python errors in your code first. Once python main.py runs without raising immediate exceptions during import/definition time, Uvicorn is more likely to load it successfully.

Cause 5: Circular Imports​

If your project has circular dependencies (Module A imports Module B, and Module B imports Module A), this can prevent modules from loading completely, leading to import errors, potentially including the one Uvicorn reports.

Solution 5: Resolve Circular Dependencies​

Refactor your code to break the circular import cycle. This often involves moving shared code/classes to a third module or rethinking the dependencies between your modules.

Cause 6: Missing Dependencies (fastapi, uvicorn)​

Ensure you have actually installed the necessary libraries in your active environment.

Solution 6: Ensure Dependencies Are Installed​

# Activate your virtual environment first!
pip install fastapi "uvicorn[standard]" # "[standard]" includes performance extras

Debugging Summary​

When facing the "Could not import module" error:

  1. Check CWD: Where is your terminal (pwd or cd)?
  2. Verify Command Path: Are you using the correct module path relative to your CWD (main:app vs src.main:app)? Use dots (.), not slashes (/).
  3. Verify Object Name: Does :app match the app = FastAPI() variable name in your file?
  4. Check for Errors: Run python your_module.py directly from its directory. Fix any syntax or import errors within your code.
  5. Check for Circular Imports: Examine your project's import structure.
  6. Confirm Installation: Ensure fastapi and uvicorn are installed in the active environment (pip list or pip show ...).

Conclusion​

The Uvicorn error Error loading ASGI app. Could not import module '...' primarily stems from path resolution issues related to your current working directory and how you specify the module path in the uvicorn command. Secondary causes include using the wrong application object name or having underlying Python errors (syntax, import, circular dependencies) within the application module itself that prevent successful loading.

By ensuring you run uvicorn from the correct directory, use proper dot notation for module paths (e.g., src.main:app), verify the :app object name, and confirm your application code is free of critical import-time errors, you can reliably resolve this common FastAPI startup issue.

Table of Contents