What causes "Could not import {module_name!r}." in pallets/flask?

Run flask from the directory containing the module, or use a file path: `flask --app path/to/myapp.py run`.

pallets/flask · error · NoAppException

Could not import {module_name!r}.

Error message

Could not import {module_name!r}.

What it means

Raised in `locate_app` when `__import__(module_name)` fails with an ImportError whose traceback has no depth — meaning the module itself could not be found at all (as opposed to error 54, where the module was found but its own imports failed). The module name is computed by `prepare_import` from the `--app` value or from wsgi.py/app.py.

Source

Thrown at src/flask/cli.py:255

    module_name: str, app_name: str | None, raise_if_not_found: t.Literal[False] = ...
) -> Flask | None: ...


def locate_app(
    module_name: str, app_name: str | None, raise_if_not_found: bool = True
) -> Flask | None:
    try:
        __import__(module_name)
    except ImportError:
        # Reraise the ImportError if it occurred within the imported module.
        # Determine this by checking whether the trace has a depth > 1.
        if sys.exc_info()[2].tb_next:  # type: ignore[union-attr]
            raise NoAppException(
                f"While importing {module_name!r}, an ImportError was"
                f" raised:\n\n{traceback.format_exc()}"
            ) from None
        elif raise_if_not_found:
            raise NoAppException(f"Could not import {module_name!r}.") from None
        else:
            return None

    module = sys.modules[module_name]

    if app_name is None:
        return find_best_app(module)
    else:
        return find_app_by_string(module, app_name)


def get_version(ctx: click.Context, param: click.Parameter, value: t.Any) -> None:
    if not value or ctx.resilient_parsing:
        return

    flask_version = importlib.metadata.version("flask")
    werkzeug_version = importlib.metadata.version("werkzeug")

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

Run flask from the directory containing the module, or use a file path: `flask --app path/to/myapp.py run`.
For src-layout / packaged projects, install the package into the env: `pip install -e .`.
Verify the name resolves manually: `python -c 'import myapp'` from the same directory and environment.
Check for typos in FLASK_APP / --app (module part, before any colon).

Example fix

# before (run from repo root, code in src/)
flask --app myapp run
# after
pip install -e .   # or: flask --app src/myapp.py run

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("myproject") is None:
    raise SystemExit("'myproject' not importable — run from the project root or pip install -e .")

Try / catch

try:
    app = info.load_app()
except NoAppException as e:
    print(f"{e} — check cwd, PYTHONPATH, and spelling", file=sys.stderr)
    sys.exit(2)

Prevention

Run flask from the directory containing the module, or pip install -e . so the package is on sys.path
Use dotted module paths without .py in --app: 'myproject.web', not 'myproject/web.py'
Check for name shadowing — a local file named like a stdlib/third-party package breaks resolution

When it happens

Trigger: `flask --app myapp run` when there is no myapp.py / myapp package on sys.path; a path-style `--app src/myapp.py` where `prepare_import` derives a dotted name that doesn't resolve (e.g. missing `__init__.py` boundaries confusing the package walk); typo in FLASK_APP.

Common situations: Running `flask` from the wrong directory so the module isn't under cwd; src-layout projects where the package isn't installed (`pip install -e .` not run); misspelled module names in FLASK_APP, Dockerfiles, or Procfiles.

Related errors

AI-assisted analysis of pallets/flask@6a2f545bfd (2026-07-31). Data as JSON: /data/errors/b4c8739e04504410.json. Report an issue: GitHub ↗.