← Retour aux tutoriels

Application Flask ne démarre pas ? Corrigez ces 6 erreurs fréquentes de débutant

flaskpythonbackenddébogagedéveloppement weberreurs courantes

Application Flask ne démarre pas ? Corrigez ces 6 erreurs fréquentes de débutant

Quand une application Flask « ne démarre pas », le symptôme est souvent trompeur : parfois le serveur démarre mais ne répond pas, parfois il répond en 404, parfois il plante immédiatement, parfois il tourne mais sur le mauvais port, etc. Ce tutoriel passe en revue 6 erreurs très fréquentes (et réalistes) chez les débutants, avec diagnostic, explication et commandes concrètes pour corriger.

Objectif : à la fin, vous saurez lancer Flask proprement, comprendre ce que fait le CLI, éviter les pièges de l’environnement Python, et diagnostiquer rapidement les erreurs de ports, d’imports, de routes, et de variables d’environnement.

Pré-requis (rapides) : vérifier votre contexte

Avant de plonger dans les erreurs, prenez 30 secondes pour vérifier :

1) Version de Python et pip

python --version
python -m pip --version

Sur macOS/Linux, vous pouvez aussi avoir python3 :

python3 --version
python3 -m pip --version

2) Flask est-il installé dans le bon environnement ?

python -m pip show flask

Si la commande ne retourne rien, Flask n’est pas installé dans cet environnement.

Structure minimale recommandée (pour suivre le tutoriel)

Voici une structure simple qui évite beaucoup de confusion :

monprojet/
  .venv/
  app.py
  requirements.txt

Exemple de app.py minimal :

from flask import Flask

app = Flask(__name__)

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

Erreur 1 — Vous lancez Flask dans le mauvais environnement (venv non activé)

Symptômes typiques

Pourquoi ça arrive

Python peut avoir plusieurs environnements (global, venv, conda, etc.). Si vous installez Flask dans un environnement et exécutez l’app dans un autre, Flask est « introuvable ».

Correction : créer et activer un venv propre

Dans le dossier du projet :

Windows (PowerShell)

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

macOS / Linux

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

Vérifiez que vous utilisez bien le Python du venv :

which python
python -c "import sys; print(sys.executable)"
python -m pip show flask

Sur Windows, which n’existe pas toujours ; utilisez :

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

Bon réflexe : figer les dépendances

Créez un requirements.txt :

python -m pip freeze > requirements.txt

Puis sur une autre machine :

python -m pip install -r requirements.txt

Erreur 2 — Vous lancez la mauvaise commande (confusion entre python app.py et flask run)

Symptômes typiques

Comprendre : deux façons de démarrer Flask

Option A — Lancer via le CLI Flask (recommandé)

Le CLI (flask run) cherche une application Flask à importer. Il a besoin de savoir où est l’objet Flask (souvent app).

Commande typique :

flask --app app run

Ici, app est le module app.py (sans .py).

Si votre objet Flask s’appelle app, c’est parfait. Si vous l’avez appelé autrement (ex: application), il faut préciser :

flask --app app:application run

Option B — Lancer via Python

Dans ce cas, vous devez avoir un bloc :

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

Puis :

python app.py

Correction recommandée (simple et moderne)

Utilisez le CLI :

flask --app app --debug run

Ancienne méthode (encore vue dans des tutos) : définir FLASK_APP. Aujourd’hui, --app est plus clair et évite des variables d’environnement oubliées.

Diagnostic rapide

Si vous voyez :

Testez l’import Python :

python -c "import app; print(app.app)"

Si cet import échoue, le problème est dans votre code (imports, nom de fichier, erreurs de syntaxe) ou votre répertoire courant.

Erreur 3 — Mauvais nom de fichier ou conflit d’import (ex: vous avez appelé votre fichier flask.py)

Symptômes typiques

Pourquoi ça arrive

Python importe des modules par nom. Si vous avez un fichier :

…vous masquez le vrai paquet. Quand vous faites from flask import Flask, Python peut importer votre fichier local au lieu du paquet Flask.

Correction

  1. Renommez le fichier en quelque chose de non conflictuel, par exemple :
  1. Supprimez les caches compilés :
find . -type d -name "__pycache__" -print
find . -type d -name "__pycache__" -exec rm -rf {} +

Sur Windows PowerShell (suppression récursive) :

Get-ChildItem -Recurse -Directory -Filter __pycache__ | Remove-Item -Recurse -Force
  1. Relancez :
flask --app app --debug run

Vérification

Assurez-vous que Flask vient bien du site-packages :

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

Le chemin doit pointer vers .venv/.../site-packages/flask/... (ou équivalent), pas vers votre projet.

Erreur 4 — L’application démarre, mais vous voyez 404 (route non définie, mauvais chemin, mauvais blueprint)

Symptômes typiques

Pourquoi ça arrive

Flask ne « devine » pas les routes. Un 404 signifie généralement :

Exemple classique d’erreur

@app.get("/hello")
def hello():
    return "Salut"

Si vous allez sur /, vous aurez 404. Il faut aller sur :

Correction : ajouter une route racine

@app.get("/")
def index():
    return "OK"

Cas des Blueprints (piège fréquent)

Exemple :

from flask import Flask, Blueprint

app = Flask(__name__)

api = Blueprint("api", __name__, url_prefix="/api")

@api.get("/status")
def status():
    return {"status": "ok"}

app.register_blueprint(api)

L’URL réelle est :

Pas /status.

Diagnostic : lister les routes connues

Flask permet d’afficher la table de routage :

flask --app app routes

Vous verrez les endpoints et les méthodes HTTP. C’est souvent le moyen le plus rapide de comprendre un 404.

Erreur 5 — Le serveur « tourne » mais n’est pas accessible (mauvais host, port occupé, firewall, Docker/WSL)

Symptômes typiques

Comprendre : 127.0.0.1 n’est accessible que localement

Par défaut, Flask écoute sur 127.0.0.1 (loopback). Cela signifie :

Correction : écouter sur toutes les interfaces

Avec le CLI :

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

Avec app.run() :

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

Port déjà utilisé : trouver et libérer le port

macOS / Linux : identifier le processus

lsof -i :5000

Puis tuer le PID :

kill -9 <PID>

Linux (alternative)

ss -ltnp | grep 5000

Windows PowerShell

Trouver le PID :

netstat -ano | findstr :5000

Tuer le processus :

taskkill /PID <PID> /F

Astuce : changer de port

flask --app app --debug run --port=8000

Puis ouvrez :

Cas Docker (très fréquent)

Si vous exécutez Flask dans un conteneur, vous devez :

  1. écouter sur 0.0.0.0 dans Flask
  2. exposer/publier le port Docker

Exemple :

docker run -p 5000:5000 monimage

Et côté Flask :

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

Erreur 6 — Le debug/reloader vous joue des tours (double lancement, variables d’environnement, code exécuté deux fois)

Symptômes typiques

Pourquoi ça arrive

En mode debug, Flask active un reloader : il démarre un processus qui surveille les fichiers, puis relance l’application quand vous modifiez le code. Cela peut donner l’impression d’un double démarrage.

Correction : protéger le code d’initialisation

Si vous avez du code « au niveau module » :

print("Initialisation...")
# création de ressources, lancement de threads, etc.

Il peut s’exécuter plusieurs fois avec le reloader.

Solution 1 : mettre l’initialisation dans un bloc if __name__ == "__main__":

from flask import Flask

app = Flask(__name__)

@app.get("/")
def home():
    return "OK"

if __name__ == "__main__":
    print("Initialisation unique (si lancement direct)")
    app.run(debug=True)

Solution 2 : désactiver le reloader (utile pour diagnostiquer)

Avec CLI :

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

Ou via app.run() :

app.run(debug=True, use_reloader=False)

Autre piège : variables d’environnement non chargées

Beaucoup de débutants créent un fichier .env et s’attendent à ce que Flask le charge automatiquement. Selon votre setup, ce n’est pas toujours le cas.

Installer python-dotenv (souvent nécessaire)

python -m pip install python-dotenv

Ensuite, Flask peut charger .env dans de nombreux cas, mais le comportement dépend des versions et de la manière dont vous lancez l’app. Le plus fiable est de définir explicitement vos variables dans votre shell, ou d’utiliser un outil dédié.

Exemple (macOS/Linux) :

export FLASK_ENV=development
export SECRET_KEY="dev"
flask --app app --debug run

Windows PowerShell :

$env:SECRET_KEY="dev"
flask --app app --debug run

Checklist de dépannage rapide (quand « ça ne démarre pas »)

1) Lire l’erreur complète

Ne vous arrêtez pas à la dernière ligne. Remontez jusqu’à la première occurrence dans la stacktrace.

2) Vérifier l’import de votre app

python -c "import app"

Si ça échoue, Flask ne pourra pas démarrer non plus.

3) Vérifier que Flask est installé dans le bon Python

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

4) Lancer explicitement avec --app et --debug

flask --app app --debug run

5) Lister les routes si vous avez des 404

flask --app app routes

6) Tester le port

Si le navigateur ne répond pas, testez avec curl :

curl -i http://127.0.0.1:5000/

Ou sur Windows (PowerShell) :

curl http://127.0.0.1:5000/ -UseBasicParsing

Exemple complet « propre » (base saine)

Copiez-collez ce fichier app.py :

from flask import Flask, jsonify

app = Flask(__name__)

@app.get("/")
def index():
    return "Serveur Flask OK"

@app.get("/api/status")
def status():
    return jsonify(status="ok")

if __name__ == "__main__":
    # Utile si vous lancez via: python app.py
    app.run(host="127.0.0.1", port=5000, debug=True)

Installez et lancez :

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
python -m pip install flask
flask --app app --debug run

Testez :

curl -i http://127.0.0.1:5000/
curl -i http://127.0.0.1:5000/api/status

Conclusion

Dans l’immense majorité des cas, une application Flask qui « ne démarre pas » tombe dans l’une de ces catégories :

  1. Mauvais environnement (Flask pas installé au bon endroit)
  2. Mauvaise commande de lancement (flask run sans --app, ou python app.py sans app.run)
  3. Conflit de noms (fichier flask.py, etc.)
  4. 404 (route inexistante, blueprint mal préfixé)
  5. Problème réseau/port (host 127.0.0.1, port occupé, Docker)
  6. Debug/reloader (double exécution, variables non chargées)

Si vous me collez le message d’erreur complet + votre structure de fichiers + la commande exacte utilisée, je peux vous dire précisément laquelle de ces erreurs s’applique et la correction minimale.

Tutoriels associés

Comment analyser et optimiser vos données avec pandas Comment lancer vos premières apps avec Docker facilement Comment utiliser CSS Flexbox pour un design responsive