Flask App Not Running? Fix These 6 Common Beginner Mistakes

When a Flask app “won’t run,” the root cause is usually not Flask itself—it’s a small setup or environment mistake that prevents the server from starting, prevents your code from importing, or makes you look at the wrong URL/port. This tutorial walks through 6 common beginner mistakes, how to diagnose them, and the exact commands to fix them.

You’ll see examples for macOS/Linux and Windows, plus practical checks you can copy/paste.

Before You Start: A Quick “Known Good” Flask App

If you’re not sure whether your project is broken or your environment is broken, start with a minimal app and compare.

Create a folder, then create app.py:

from flask import Flask

app = Flask(__name__)

@app.get("/")
def home():
    return "Hello, Flask!"

Install Flask (preferably inside a virtual environment—covered below):

python -m pip install flask

Run it (newer Flask versions support flask --app):

flask --app app run

You should see output similar to:

 * Serving Flask app 'app'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit

Then open:

• http://127.0.0.1:5000

If this minimal app runs but your project doesn’t, the issue is likely in your project structure/imports/config. If even this minimal app fails, the issue is likely Python/Flask installation or environment.

Mistake 1: Running the Wrong Command (or Using the Wrong Entry Point)

Symptoms

• flask: command not found
• Error: Could not locate a Flask application.
• It runs, but not your app
• You run python app.py and nothing happens (or it exits immediately)

Why it happens

Flask can be run in multiple ways:

1. flask --app app run (recommended modern CLI approach)
2. Setting environment variable FLASK_APP then running flask run
3. python app.py (only works if you call app.run() in if __name__ == "__main__":)

Beginners often mix these approaches and end up pointing Flask at the wrong module, or they run python app.py without a run() call.

Fix

Option A (recommended): Use flask --app

From the directory containing app.py:

flask --app app run

If your file is named main.py, use:

flask --app main run

If your Flask instance is not named app (for example application = Flask(__name__)), specify it:

flask --app app:application run

Option B: Use python -m flask when flask isn’t found

Sometimes the flask executable isn’t on PATH, but Flask is installed. Try:

python -m flask --app app run

This uses the current Python interpreter directly.

Option C: Run with python app.py (only if you add app.run())

Add this at the bottom of your file:

if __name__ == "__main__":
    app.run(debug=True)

Then run:

python app.py

Diagnostic commands

Check which flask you’re calling:

macOS/Linux:

which flask
flask --version
python --version
python -m pip show flask

Windows (PowerShell):

Get-Command flask
flask --version
python --version
python -m pip show flask

If flask --version fails but python -m pip show flask shows it installed, use python -m flask ... or fix your environment (see Mistake 2).

Mistake 2: Flask Installed in the Wrong Python Environment (Virtualenv Confusion)

Symptoms

• ModuleNotFoundError: No module named 'flask'
• flask: command not found
• Your IDE runs it, but terminal doesn’t (or vice versa)
• You installed Flask, but it still can’t import

Why it happens

You might have:

• Multiple Python versions installed (system Python + Homebrew Python + Anaconda + pyenv)
• Installed Flask globally but you’re running a different Python
• Activated the wrong virtual environment (or none)

Flask must be installed into the same Python environment that runs your app.

Fix: Create and use a virtual environment (recommended)

From your project folder:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install flask

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install flask

Now run:

python -m flask --app app run

Confirm you’re using the right interpreter

After activating the venv:

macOS/Linux:

which python
which pip
python -m pip show flask

Windows (PowerShell):

Get-Command python
Get-Command pip
python -m pip show flask

The paths should point inside .venv.

Common pitfall: pip vs python -m pip

When multiple Pythons exist, pip might install into a different interpreter than python. Prefer:

python -m pip install flask

That guarantees the install goes to the Python you’re using.

Mistake 3: Incorrect Project Structure and Imports (Circular Imports, Wrong Module Names)

Symptoms

• Error: Could not import 'app'
• ImportError / ModuleNotFoundError for your own files
• Circular import errors
• It works when you run from one folder, fails from another

Why it happens

Flask’s CLI imports your app as a module. That means Python import rules apply.

Common beginner issues:

• Naming your file flask.py (conflicts with the Flask package)
• Naming your file app.py but running from the wrong working directory
• Creating a package but missing __init__.py (less common in modern Python, but still relevant in some setups)
• Circular imports: app.py imports routes.py, and routes.py imports app at import time

Fix A: Don’t name your files like installed packages

Avoid these filenames in your project root:

• flask.py
• requests.py
• json.py
• typing.py

If you have flask.py, Flask will try to import your file instead of the real Flask library, causing confusing errors.

Rename it to something like server.py or main.py.

Then run:

python -m flask --app server run

Fix B: Use an application factory for larger apps

A robust structure:

yourproject/
  app/
    __init__.py
    routes.py
  wsgi.py

app/__init__.py:

from flask import Flask

def create_app():
    app = Flask(__name__)

    from .routes import bp
    app.register_blueprint(bp)

    return app

app/routes.py:

from flask import Blueprint

bp = Blueprint("main", __name__)

@bp.get("/")
def home():
    return "Hello from blueprint!"

wsgi.py:

from app import create_app

app = create_app()

Run:

python -m flask --app wsgi run

This pattern prevents many circular import problems because the app is created in a function, and routes are registered after the app exists.

Fix C: Ensure you run commands from the correct directory

If app.py is in myproject/, you must run from myproject/:

cd myproject
python -m flask --app app run

If you run flask from the parent directory, Python may not find your module.

Diagnostic commands

Print your working directory:

macOS/Linux:

pwd
ls

Windows (PowerShell):

Get-Location
dir

If your app file isn’t listed, you’re in the wrong directory.

Mistake 4: Debug Mode / Reloader Confusion (App “Runs Twice,” Changes Not Applying, or Crash Loops)

Symptoms

• The server starts, then restarts repeatedly
• Your print statements appear twice
• You change code but nothing updates
• You see errors related to the reloader or multiprocessing on Windows

Why it happens

Flask’s debug mode uses an auto-reloader. The reloader starts a parent process that watches files, and a child process that runs the app. That can cause:

• Code in global scope running twice
• Confusing logs
• In some edge cases, reloader issues depending on environment

Also, if you don’t enable debug mode, code changes won’t reload automatically.

Fix: Enable debug mode correctly

Modern Flask:

flask --app app --debug run

Or:

python -m flask --app app --debug run

If you want to disable the reloader (to stop double execution):

flask --app app --debug run --no-reload

Fix: Avoid side effects at import time

Don’t do heavy work at import time, because the reloader may import twice. For example, avoid this at top-level:

# Avoid: runs at import time
print("Starting up...")
initialize_database()

Instead, do it in a guarded block or inside a function called once:

def init_once():
    print("Starting up...")
    # initialize_database()

if __name__ == "__main__":
    init_once()
    app.run(debug=True)

If you’re using the Flask CLI, you can use before_first_request (older pattern) or initialize in create_app().

Diagnostic tip: Confirm debug status

When running, Flask prints whether debug is on. You can also check:

app.debug

But remember: debug can be enabled by CLI flags even if app.debug isn’t set in code the way you expect.

Mistake 5: Binding to the Wrong Host/Port (It Runs, But You Can’t Access It)

Symptoms

• Terminal says it’s running, but browser can’t connect
• Works on 127.0.0.1 but not from another device
• You used a different port and forgot
• You’re on a remote machine (VM, Docker, WSL) and can’t reach it

Why it happens

By default, Flask binds to 127.0.0.1 (localhost). That means it only accepts connections from the same machine.

Also, if port 5000 is already used, Flask may fail to start or you may have another service on that port.

Fix A: Use the URL Flask prints

Flask prints something like:

• Running on http://127.0.0.1:5000

Use that exact URL.

If you typed http://localhost:8000 out of habit, it won’t work unless you started on port 8000.

Fix B: Change the port

flask --app app run --port 8000

Then visit:

• http://127.0.0.1:8000

Fix C: Bind to all interfaces (for LAN / Docker / VM access)

flask --app app run --host 0.0.0.0 --port 5000

Then from another device on your network, use your machine’s LAN IP:

• http://YOUR_LAN_IP:5000

Find your IP:

macOS/Linux:

ip addr | grep inet
# or
ifconfig

Windows (PowerShell):

ipconfig

Fix D: Check if the port is already in use

macOS/Linux:

lsof -i :5000

Windows (PowerShell):

netstat -ano | findstr :5000

If another process is using it, either stop that process or choose another port.

Mistake 6: Missing Dependencies or Runtime Errors Preventing Startup (Reading the Traceback Incorrectly)

Symptoms

• The server never starts
• You see a long traceback
• ModuleNotFoundError for packages like python-dotenv, flask_sqlalchemy, requests, etc.
• Syntax errors, indentation errors, or mis-typed decorators
• Errors occur only when you hit a route (not at startup)

Why it happens

Flask imports your app module at startup. Any error during import prevents the server from running. Additionally, some errors only happen when a route is accessed.

Beginners often scroll to the top of the traceback and miss the key line at the bottom that states the real error.

Fix A: Read the traceback from the bottom up

Example:

ModuleNotFoundError: No module named 'flask_sqlalchemy'

That means you need to install it in the active environment:

python -m pip install flask_sqlalchemy

If you’re using a requirements.txt, install everything:

python -m pip install -r requirements.txt

Fix B: Generate and use requirements.txt (so installs are repeatable)

Freeze your environment:

python -m pip freeze > requirements.txt

On another machine (or after recreating .venv):

python -m pip install -r requirements.txt

Fix C: Catch common syntax and decorator mistakes

A frequent bug is forgetting parentheses:

@app.route("/")
def home():
    return "hi"

This is correct. But this is wrong:

@app.route
def home():
    return "hi"

Another frequent issue is indentation:

@app.get("/")
def home():
return "hi"   # IndentationError

Python will stop immediately with an IndentationError.

Fix D: Confirm your code can be imported

Try importing your module directly:

python -c "import app; print('import ok')"

If this fails, Flask won’t run either. The traceback from this command is often simpler than the Flask CLI output.

Fix E: Turn on debug to get better error pages

flask --app app --debug run

Then when you hit a route that errors, you’ll get a detailed interactive traceback in the browser (only for development).

A Practical Debugging Checklist (Copy/Paste Friendly)

When your Flask app won’t run, go through this in order.

1) Confirm you’re in the right folder

macOS/Linux:

pwd
ls

Windows (PowerShell):

Get-Location
dir

2) Confirm the Python environment

python --version
python -m pip --version
python -m pip show flask

If Flask isn’t shown, install it:

python -m pip install flask

3) Run using a reliable command

python -m flask --app app --debug run

If your file isn’t app.py, change --app accordingly.

4) If it fails, test importing

python -c "import app"

Fix whatever traceback you get (missing dependencies, syntax errors, circular imports, etc.).

5) If it runs but you can’t connect, verify host/port

Try:

flask --app app run --host 0.0.0.0 --port 5000

Then use the printed URL and ensure port isn’t blocked/in use.

Common “It Still Doesn’t Work” Scenarios

“I installed Flask but flask command still isn’t found”

Use:

python -m flask --app app run

If that works, it’s a PATH issue. The simplest fix is to always use python -m flask inside your venv.

“My app is called application.py and my Flask variable is server”

Run:

python -m flask --app application:server run

“I’m on Windows and activation is blocked”

PowerShell may block scripts. You can set execution policy for your user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then activate again:

.\.venv\Scripts\Activate.ps1

(If you’re in a locked-down environment, ask your admin rather than changing policies.)

“I’m using WSL/Docker and can’t access from my browser”

Bind to 0.0.0.0:

flask --app app run --host 0.0.0.0 --port 5000

For Docker, you must also publish ports, e.g.:

docker run -p 5000:5000 yourimage

Summary: The 6 Mistakes and the Fast Fixes

1. Wrong run command / wrong entry point
   Use: python -m flask --app app run (or flask --app app run)

2. Flask installed in the wrong environment
   Create/activate venv, then: python -m pip install flask

3. Bad structure/import conflicts (e.g., flask.py)
   Rename conflicting files; run from correct directory; consider app factory

4. Debug/reloader confusion
   Use: flask --app app --debug run and avoid side effects at import time

5. Wrong host/port
   Use: --port 8000 or --host 0.0.0.0 and check port conflicts

6. Missing dependencies or runtime errors
   Read traceback bottom-up; python -m pip install -r requirements.txt; test python -c "import app"

Next Steps (Optional, But Strongly Recommended)

If you want your Flask projects to be consistently runnable:

• Always use a project-local virtual environment (.venv)
• Run Flask via python -m flask ... to avoid PATH confusion
• Use an application factory for anything beyond a single-file app
• Keep a requirements.txt and install from it on new machines

If you paste the exact error output (traceback) and your folder structure (file tree), it becomes much easier to pinpoint which of the 6 mistakes you’re hitting.