Flask-app start niet? Los 6 veelgemaakte beginnersfouten op

Als je Flask-app niet start, voelt het vaak alsof “alles klopt” en toch gebeurt er niets (of je krijgt een cryptische fout). In deze tutorial los je 6 veelgemaakte beginnersfouten op met diepe uitleg, concrete commando’s en een praktische checklist. Je leert niet alleen wat je moet doen, maar vooral waarom het werkt—zodat je dit soort problemen voortaan sneller zelf debugt.

Vooraf: snelle diagnose (doe dit eerst)

Voordat je in de details duikt: verzamel basisinformatie. Dit voorkomt dat je in het wilde weg gaat proberen.

1) Welke Python en pip gebruik je?

python --version
python -c "import sys; print(sys.executable)"
pip --version

Op veel systemen bestaat ook python3 en pip3:

python3 --version
python3 -c "import sys; print(sys.executable)"
pip3 --version

Waarom dit belangrijk is:
Als je per ongeluk pip van een andere Python-installatie gebruikt dan waarmee je je app start, installeer je Flask in de “verkeerde” omgeving. Dan krijg je bijvoorbeeld ModuleNotFoundError: No module named 'flask' of start je een andere versie van je code dan je denkt.

2) Kun je Flask importeren?

python -c "import flask; print(flask.__version__)"

Als dit faalt, is Flask niet geïnstalleerd in de interpreter die je gebruikt om te starten.

3) Welke foutmelding krijg je precies?

Start je app en kopieer de volledige stacktrace:

python app.py

Of als je via Flask CLI start:

flask run

Zonder de volledige foutmelding is het vaak gokken.

Fout 1 — Flask is niet geïnstalleerd in je (virtuele) omgeving

Symptomen

• ModuleNotFoundError: No module named 'flask'
• Of: flask: command not found
• Of: je IDE zegt dat import flask rood onderstreept

Oorzaak (dieper uitgelegd)

Python-projecten horen vrijwel altijd in een virtuele omgeving te draaien. Dat is een geïsoleerde map met eigen packages. Beginners installeren Flask soms “globaal” (system-wide), maar starten de app met een andere Python. Of ze maken wel een venv, maar activeren die niet.

Oplossing (Windows)

Maak een venv:

python -m venv .venv

Activeer:

.venv\Scripts\activate

Installeer Flask:

python -m pip install --upgrade pip
python -m pip install flask

Controleer:

python -c "import flask; print(flask.__version__)"

Oplossing (macOS/Linux)

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install flask
python -c "import flask; print(flask.__version__)"

Extra: “flask” commando werkt niet

Soms is Flask geïnstalleerd, maar je shell vindt het flask-commando niet (PATH-probleem). Gebruik dan altijd:

python -m flask --version
python -m flask run

Waarom dit werkt:
python -m flask draait Flask via de interpreter die je expliciet aanroept. Dat omzeilt PATH-issues en mismatches tussen Python-installaties.

Fout 2 — Verkeerde projectstructuur of verkeerde FLASK_APP

Symptomen

• Error: Could not locate a Flask application.
• Error: Failed to find Flask application or factory in module ...
• ImportError bij flask run

Oorzaak (dieper uitgelegd)

De Flask CLI (flask run) moet weten waar jouw app-object staat. Dat kan op twee manieren:

1. Je hebt een bestand app.py of wsgi.py met een variabele app = Flask(__name__) in de root van je project.
2. Je gebruikt een package-structuur en een “application factory” (create_app()).

Beginners hebben vaak:

• een bestand dat anders heet (main.py, server.py) zonder FLASK_APP te zetten,
• of de app staat in een submap,
• of de variabele heet anders dan app.

Correcte minimale setup (simpel)

Bestand: app.py

from flask import Flask

app = Flask(__name__)

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

Starten:

python -m flask run

Als Flask je app niet vindt, zet expliciet FLASK_APP.

Windows (PowerShell)

$env:FLASK_APP = "app.py"
python -m flask run

macOS/Linux (bash/zsh)

export FLASK_APP=app.py
python -m flask run

Als je bestand main.py heet

export FLASK_APP=main.py
python -m flask run

Of op Windows PowerShell:

$env:FLASK_APP = "main.py"
python -m flask run

Package-structuur met factory (iets geavanceerder, maar robuust)

Structuur:

project/
  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 "Hallo vanuit blueprint!"

wsgi.py

from app import create_app
app = create_app()

Starten:

export FLASK_APP=wsgi.py
python -m flask run

Waarom dit belangrijk is:
Zodra je project groeit (blueprints, config, tests) is een factory-setup vaak stabieler. Maar de CLI moet dan wel weten welke module/variabele het startpunt is.

Fout 3 — Je start de app “goed”, maar je debug/host/port instellingen kloppen niet

Symptomen

• Terminal zegt dat de server draait, maar je browser laadt niets
• Je ziet Running on http://127.0.0.1:5000 maar je probeert localhost:8000
• Je draait in een container/VM en kunt de server niet bereiken
• Je krijgt “This site can’t be reached”

Oorzaak (dieper uitgelegd)

Flask bindt standaard aan 127.0.0.1 (loopback). Dat is alleen bereikbaar vanaf dezelfde machine. In Docker, WSL, een VM of op een remote server betekent dit: niet bereikbaar van buiten.

Ook wordt standaard poort 5000 gebruikt. Als jij naar een andere poort surft, lijkt het alsof de app niet werkt.

Oplossing: expliciet host en port

Via Flask CLI:

python -m flask run --host=0.0.0.0 --port=5000

Via app.run() (alleen voor development):

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

Controleer of de poort echt luistert

macOS/Linux:

lsof -i :5000

Of:

ss -ltnp | grep 5000

Windows (PowerShell):

netstat -ano | findstr :5000

Snelle test met curl

curl -i http://127.0.0.1:5000/

Als curl wel werkt maar je browser niet, zit het probleem vaak in:

• proxy-instellingen,
• verkeerde URL,
• caching (probeer incognito),
• of je zit in een andere omgeving (bijv. WSL vs Windows).

Poortconflict: “Address already in use”

Als je ziet:

• OSError: [Errno 98] Address already in use
• of Windows: Only one usage of each socket address...

Dan gebruikt een ander proces poort 5000. Kies een andere poort:

python -m flask run --port=5001

Of stop het proces dat de poort bezet houdt.

Fout 4 — Import-cirkels en naamconflicten (bijv. je noemt je bestand flask.py)

Symptomen

• ImportError: cannot import name 'Flask' from partially initialized module ...
• AttributeError op dingen die “normaal bestaan”
• Vage importproblemen die pas bij starten optreden

Oorzaak (dieper uitgelegd)

Python importeert modules op basis van bestandsnamen in je projectmap én de sys.path. Als jij een bestand flask.py noemt, dan doet:

import flask

niet wat je denkt: Python importeert jouw lokale flask.py in plaats van het echte Flask-package. Hetzelfde geldt voor namen als requests.py, json.py, email.py, enz.

Daarnaast ontstaan import-cirkels wanneer module A module B importeert en B weer A importeert. Dit kan gebeuren als je alles in één keer “aan elkaar knoopt” (app-object, routes, models) zonder structuur.

Oplossing 1: hernoem conflicterende bestanden

Controleer je projectmap:

ls

Als je ziet:

• flask.py
• flask/ (map)
• typing.py, json.py, etc.

Hernoem het bestand, bijvoorbeeld naar app.py of server.py.

Verwijder ook de __pycache__ zodat oude imports niet blijven hangen:

macOS/Linux:

find . -type d -name "__pycache__" -print -exec rm -r {} +

Windows (PowerShell):

Get-ChildItem -Recurse -Directory -Filter "__pycache__" | Remove-Item -Recurse -Force

Oplossing 2: voorkom import-cirkels met blueprints

Een veelvoorkomende beginnersstructuur:

• app.py maakt app = Flask(__name__)
• routes.py importeert app uit app.py
• app.py importeert routes om routes te registreren

Dat is een cirkel.

Beter:

• Maak app in __init__.py of in create_app()
• Gebruik Blueprint in routes.py
• Registreer de blueprint in de factory

(zie de factory-structuur bij Fout 2)

Waarom dit werkt:
Blueprints laten je routes definiëren zonder direct het globale app-object te importeren. Zo verbreek je de cirkel.

Fout 5 — Templates/static paden kloppen niet (app start “wel”, maar je ziet errors bij requests)

Symptomen

• App start, maar bij openen van / krijg je:
  • jinja2.exceptions.TemplateNotFound: index.html
• Of je CSS/JS laadt niet (404 op /static/...)
• Je denkt “de app start niet”, maar eigenlijk crasht hij bij de eerste request

Oorzaak (dieper uitgelegd)

Flask zoekt standaard:

• templates in een map templates/ naast je app-module
• static files in static/

Als je projectstructuur anders is, of je start vanuit een andere werkdirectory, kan Flask je templates niet vinden.

Ook beginners plaatsen templates per ongeluk in template/ (zonder s), of in een submap die Flask niet kent.

Correcte minimale structuur

project/
  app.py
  templates/
    index.html
  static/
    style.css

app.py

from flask import Flask, render_template

app = Flask(__name__)

@app.get("/")
def home():
    return render_template("index.html")

templates/index.html

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
  </head>
  <body>
    <h1>Hallo Flask</h1>
  </body>
</html>

Als je een afwijkende structuur hebt

Je kunt Flask vertellen waar templates/static staan:

app = Flask(__name__, template_folder="web/templates", static_folder="web/static")

Debug tip: print waar je app draait

import os
print("CWD:", os.getcwd())

Waarom dit helpt:
Veel template-problemen zijn eigenlijk “ik start vanuit de verkeerde map”. Start bij voorkeur altijd vanuit je projectroot.

Fout 6 — Je gebruikt de verkeerde startmethode of debug-instellingen (en krijgt dubbele starts / rare gedrag)

Symptomen

• De server start twee keer
• Code wijzigingen worden niet herladen
• flask run werkt anders dan python app.py
• Je ziet “* Restarting with stat” en denkt dat het een fout is

Oorzaak (dieper uitgelegd)

Er zijn grofweg twee manieren om Flask te starten in development:

1. python app.py met app.run(...)
2. flask run (Flask CLI)

Beide kunnen werken, maar ze hebben andere verwachtingen (zoals FLASK_APP, debug, reloader).

De debug reloader start vaak een extra proces om codewijzigingen te detecteren. Dat is normaal, maar kan verwarrend zijn. Als jij bij import-time side effects hebt (bijv. “seed database”, “start scheduler”), dan gebeurt dat dubbel.

Beste practice: gebruik Flask CLI voor development

Zet debug aan:

macOS/Linux:

export FLASK_APP=app.py
export FLASK_DEBUG=1
python -m flask run

Windows PowerShell:

$env:FLASK_APP="app.py"
$env:FLASK_DEBUG="1"
python -m flask run

Voorkom side effects bij import

Zet “run code” achter:

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

En verplaats zware initialisatie naar functies of naar create_app().

Als je per se python app.py gebruikt

Zorg dat je debug expliciet aanzet:

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

Waarom dit belangrijk is:
Beginners mixen vaak beide methodes door elkaar, waardoor ze denken dat instellingen “niet werken”. Kies één workflow en houd die consistent.

Praktische checklist: van foutmelding naar fix

Gebruik deze checklist als je app niet start:

1. Zit je in de juiste map?

   pwd
   ls

2. Gebruik je de juiste Python?

   python -c "import sys; print(sys.executable)"

3. Is Flask geïnstalleerd in die Python?

   python -c "import flask; print(flask.__version__)"

4. Start je op een consistente manier?
   • bij voorkeur:

     python -m flask run

5. Kan Flask je app vinden?

   export FLASK_APP=app.py
   python -m flask run

6. Luistert de server op de host/port die je gebruikt?

   python -m flask run --host=127.0.0.1 --port=5000
   curl -i http://127.0.0.1:5000/

7. Heb je naamconflicten?
   • geen flask.py, json.py, etc.
   • verwijder __pycache__
8. Krijg je errors pas bij het openen van een route?
   • check templates/static paden
   • lees de stacktrace tot de eerste regel die naar jouw code wijst

Veelvoorkomende foutmeldingen (en wat ze meestal betekenen)

ModuleNotFoundError: No module named 'flask'

• Flask niet geïnstalleerd in de actieve interpreter/venv
• Oplossing: activeer venv, installeer met python -m pip install flask

Error: Could not locate a Flask application.

• FLASK_APP niet gezet of app-object heet niet app
• Oplossing: export FLASK_APP=app.py of correct factory/wsgi

OSError: [Errno 98] Address already in use

• Poort bezet
• Oplossing: andere poort of proces stoppen

jinja2.exceptions.TemplateNotFound

• templates/ map ontbreekt of verkeerde werkdirectory
• Oplossing: juiste structuur of template_folder=...

ImportError: cannot import name ... from partially initialized module

• Import-cirkel of naamconflict
• Oplossing: herstructureren (blueprints/factory), hernoemen, cache opruimen

Aanbevolen “gezonde” basis voor beginners (copy-paste project)

Maak een nieuwe map en zet dit neer:

flask-demo/
  .venv/
  app.py
  templates/
    index.html

Installeren en starten

macOS/Linux:

cd flask-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install flask
export FLASK_APP=app.py
export FLASK_DEBUG=1
python -m flask run

Windows PowerShell:

cd flask-demo
python -m venv .venv
.venv\Scripts\activate
python -m pip install flask
$env:FLASK_APP="app.py"
$env:FLASK_DEBUG="1"
python -m flask run

app.py

from flask import Flask, render_template

app = Flask(__name__)

@app.get("/")
def home():
    return render_template("index.html")

templates/index.html

<!doctype html>
<html lang="nl">
  <head>
    <meta charset="utf-8" />
    <title>Flask werkt</title>
  </head>
  <body>
    <h1>Als je dit ziet, start je Flask-app correct.</h1>
  </body>
</html>

Tot slot: hoe je sneller debugt als het weer gebeurt

• Lees de stacktrace van onder naar boven tot je bij jouw bestanden komt.
• Maak je probleem kleiner: start met één route (/) zonder database, zonder extra imports.
• Voeg daarna stap voor stap onderdelen toe (templates, config, database).
• Houd je omgeving schoon:

  python -m pip freeze

• Werk consistent met een venv en python -m flask run.

Als je de exacte foutmelding (hele stacktrace) en je projectstructuur (bestandsboom) plakt, kan ik gericht aanwijzen welke van de 6 fouten het is en wat je in jouw code moet aanpassen.