Flask: Could not locate a Flask application (tested)

Error: Could not locate a Flask application. means flask run found no --app option, no FLASK_APP variable, and no app.py or wsgi.py in the current directory. Run flask --app yourmodule run from the directory containing it.

Setup: p1/web.py creates the app under a non-standard name, and p2/app.py imports a package that is not installed:

from flask import Flask
server = Flask(__name__)

from flask import Flask
import not_installed_pkg
app = Flask(__name__)

1. The messages and what each means

cd /w/p1
echo '$ flask run          (only web.py here, no app.py/wsgi.py)'; timeout 3 flask run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log
echo '$ flask --app web run'; timeout 3 flask --app web run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log
echo '$ flask --app web:server run'; timeout 3 flask --app web:server run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log
echo '$ FLASK_APP=web:server flask run'; FLASK_APP=web:server timeout 3 flask run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log
echo '$ flask --app web:app run'; timeout 3 flask --app web:app run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log
echo '$ flask --app nope run'; timeout 3 flask --app nope run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log
cd /w/p2
echo '$ flask run          (app.py imports a missing package)'; timeout 3 flask run > /tmp/f.log 2>&1; grep -m1 -E "Error|Running" /tmp/f.log

Output:

$ flask run          (only web.py here, no app.py/wsgi.py)
Error: 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.
$ flask --app web run
 * Running on http://127.0.0.1:5000
$ flask --app web:server run
 * Running on http://127.0.0.1:5000
$ FLASK_APP=web:server flask run
 * Running on http://127.0.0.1:5000
$ flask --app web:app run
Error: Failed to find attribute 'app' in 'web'.
$ flask --app nope run
Error: Could not import 'nope'.
$ flask run          (app.py imports a missing package)
Error: While importing 'app', an ImportError was raised:

Without --app or FLASK_APP, flask run only looks for wsgi.py or app.py in the current directory, hence Could not locate a Flask application. With --app web, Flask imports web and finds the app on its own (here the only Flask instance, even though it is called server), so you rarely need the :name part; if you give one, it must be right, or you get Failed to find attribute. Could not import 'nope' means no such module from the current directory.

2. "While importing 'app', an ImportError was raised"

Here Flask found app.py, but importing it failed. The full traceback follows that line in the terminal; its last line is the real problem (here a missing package). Install it in the same environment as the flask command (python -m flask run guarantees the same interpreter).

Checklist

Name the file app.py or wsgi.py, or pass flask --app yourmodule run (Flask 2.2+; older versions use FLASK_APP=yourmodule).
Run from the directory that contains the module, or use a dotted path (--app package.module).
App factory: --app "yourpackage:create_app()".
Read the traceback under "While importing": it is an error in your code, not in Flask's discovery.

Frequently asked questions

How do I fix Could not locate a Flask application?

Run flask --app yourmodule run (or set FLASK_APP=yourmodule) from the directory that contains yourmodule.py, or name the file app.py or wsgi.py.

Do I need to write module:app with flask --app?

Usually not. Flask 3.1.3 found the single Flask instance in the module even when it was named server. If you give a name, it must match, or you get Failed to find attribute.

What does While importing app, an ImportError was raised mean?

Flask found app.py but your code failed to import, often a missing package. The traceback after that line shows the real error.

Written with AI assistance. Measured on 2026-10-23 with Flask 3.1.3 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 and Flask are free.