FastAPI "ModuleNotFoundError: No module named 'app'" in CI

By Kaveh Alemi·Latchkey

The runner started pytest or uvicorn from a directory where your app package is not importable. sys.path does not include the project root, so import app or app.main:app fails even though it works locally.

What this error means

A test run or uvicorn app.main:app fails with "ModuleNotFoundError: No module named 'app'" although the same command works on your machine.

ERROR: Error loading ASGI app. Could not import module "app.main".
Traceback (most recent call last):
  File ".../uvicorn/importer.py", line 22, in import_from_string
    module = importlib.import_module(module_str)
ModuleNotFoundError: No module named 'app'

Common causes

The project is not installed and the root is not on sys.path

CI runs from a subdirectory, or the package was never installed with pip install -e ., so the app package is not importable from where the command runs.

A src layout without PYTHONPATH configured

Your code lives under src/app, but neither an editable install nor PYTHONPATH=src puts it on the import path in CI.

How to fix it

Install the project editable from the root

1. Run the step from the directory that holds pyproject.toml.
2. Install the package so app is importable like in production.
3. Re-run pytest or uvicorn against the installed package.

python -m pip install -e .
uvicorn app.main:app --host 0.0.0.0 --port 8000

Set PYTHONPATH for a src layout

If you do not install the package, add the directory that contains app to the import path in the job env.

env:
  PYTHONPATH: ${{ github.workspace }}

How to prevent it

• Install your FastAPI project editable in CI so imports match production.
• Keep pytest rootdir at the project root with a pyproject.toml or pytest.ini.
• Avoid depending on the current working directory being on sys.path.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation