pallets/flask · error · NoAppException

Could not locate a Flask application. Use the 'flask --app'

Error message

Could not locate a Flask application. Use the 'flask --app' option, 'FLASK_APP' environment variable, or a 'wsgi.py' or 'app.py' file in the current directory.

What it means

Raised by `ScriptInfo.load_app` when every discovery path came up empty: no `create_app` callback was configured, no `--app`/FLASK_APP import path was given, and the automatic fallback probe of `wsgi.py` and `app.py` in the current directory (tried with `raise_if_not_found=False`) found no Flask app. It is Flask's generic 'I have nothing to run' error.

Source

Thrown at src/flask/cli.py:359

        if self.create_app is not None:
            app = self.create_app()
        else:
            if self.app_import_path:
                path, name = (
                    re.split(r":(?![\\/])", self.app_import_path, maxsplit=1) + [None]
                )[:2]
                import_name = prepare_import(path)
                app = locate_app(import_name, name)
            else:
                for path in ("wsgi.py", "app.py"):
                    import_name = prepare_import(path)
                    app = locate_app(import_name, None, raise_if_not_found=False)

                    if app is not None:
                        break

        if app is None:
            raise NoAppException(
                "Could not locate a Flask application. Use the"
                " 'flask --app' option, 'FLASK_APP' environment"
                " variable, or a 'wsgi.py' or 'app.py' file in the"
                " current directory."
            )

        if self.set_debug_flag:
            # Update the app's debug flag through the descriptor so that
            # other values repopulate as well.
            app.debug = get_debug_flag()

        self._loaded_app = app
        return app


pass_script_info = click.make_pass_decorator(ScriptInfo, ensure=True)

F = t.TypeVar("F", bound=t.Callable[..., t.Any])

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

Pass the app explicitly: `flask --app path.to.module run` (or `--app module:create_app`).
Set the environment variable: `export FLASK_APP=myapp` (and install python-dotenv if you rely on .flaskenv/.env to set it).
Rename or add a wsgi.py/app.py in the working directory that exposes `app` or `create_app`, or `cd` to the directory that has one.

Example fix

# before
flask run   # app lives in server.py
# after
flask --app server run

Defensive patterns

Strategy: validation

Validate before calling

import os, pathlib
ok = os.environ.get("FLASK_APP") or any(pathlib.Path(f).exists() for f in ("wsgi.py", "app.py"))
if not ok:
    raise SystemExit("Set --app/FLASK_APP or add app.py/wsgi.py in the cwd")

Try / catch

try:
    app = info.load_app()
except NoAppException as e:
    print(e, file=sys.stderr)
    sys.exit(2)

Prevention

Name your entry module app.py or wsgi.py to get auto-discovery for free
Otherwise always pass --app pkg.module:attr or export FLASK_APP (a .flaskenv file makes it persistent)
Run flask from the project root — discovery only scans the current directory

When it happens

Trigger: Running `flask run`, `flask shell`, or `flask routes` in a directory containing neither wsgi.py nor app.py, with FLASK_APP unset and no --app option; or wsgi.py/app.py exist but contain no discoverable Flask instance or factory.

Common situations: Running the CLI from the repo root when the app lives in a subdirectory; the app file named something else (main.py, server.py); FLASK_APP defined in a .env file that isn't loaded because python-dotenv isn't installed; CI/Docker workdir mismatch.

Related errors

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