Installer Gunicorn : guide pratique pour Django et Flask

Gunicorn (Green Unicorn) est un serveur HTTP Python compatible WSGI, utilisé pour exécuter des applications web comme Django et Flask en production. Son installation tient en une commande ; l'essentiel est de savoir comment lancer votre application et de connaître une limitation de plateforme qui bloque de nombreux utilisateurs avant même leurs premiers essais.

Installer Gunicorn

Gunicorn est un paquet PyPI standard. Dans l'environnement virtuel de votre projet :

pip install gunicorn

Vérifiez que l'installation a réussi et contrôlez la version :

gunicorn --version

Ajoutez-le à votre fichier de dépendances afin de garantir des déploiements reproductibles — par exemple, avec une ligne dans requirements.txt :

gunicorn==23.0.0

Lancer une application Django

Gunicorn sert votre application via son point d'entrée WSGI. Pour un projet Django, il s'agit de l'objet appelable application défini dans le fichier wsgi.py de votre projet. Depuis le répertoire qui contient manage.py :

gunicorn myproject.wsgi:application

Remplacez myproject par le dossier qui contient vos fichiers settings.py et wsgi.py. La syntaxe est module:callable : la partie avant les deux-points correspond au chemin d'importation et celle qui suit désigne l'objet appelable WSGI qu'il contient.

Lancer une application Flask

Avec Flask, indiquez à Gunicorn le module et l'objet de l'application. Si votre application est définie ainsi : app = Flask(__name__) dans app.py :

gunicorn app:app

Le premier app désigne le fichier (app.py) et le second l'instance Flask qu'il contient.

Options courantes : bind et workers

Par défaut, Gunicorn écoute sur 127.0.0.1:8000, une adresse qui n'accepte que les connexions locales. Pour écouter sur toutes les interfaces — par exemple derrière un reverse proxy comme Nginx — définissez l'adresse de liaison ainsi que le nombre de processus workers :

gunicorn myproject.wsgi:application --bind 0.0.0.0:8000 --workers 3

Pour commencer, on utilise souvent la formule (2 × nombre_de_cœurs_CPU) + 1 pour déterminer le nombre de workers. Chaque worker synchrone traite une seule requête à la fois : augmenter leur nombre permet donc de gérer davantage de requêtes simultanées, dans la limite des ressources disponibles sur votre processeur et votre mémoire. Ajustez ensuite ce paramètre selon votre charge de travail.

Le piège de Windows

Gunicorn ne fonctionne pas nativement sous Windows. Il dépend de fonctionnalités propres à Unix, comme le module fcntl et le modèle de workers fondé sur fork. Ainsi, pip install gunicorn peut réussir, mais gunicorn échouera au lancement sous Windows natif. Si vous utilisez Windows, exécutez-le dans WSL (Windows Subsystem for Linux), dans un conteneur Linux ou sur un serveur Linux — ou utilisez plutôt un serveur WSGI compatible avec Windows, comme Waitress, pour le développement local.

À propos des applications asynchrones

Gunicorn est un serveur WSGI, ce qui convient aux applications Django et Flask standard. Si vous utilisez une application ASGI/asynchrone (FastAPI ou Django en mode ASGI), vous aurez besoin d'une configuration compatible avec ASGI — par exemple Gunicorn avec des workers Uvicorn, ou Uvicorn exécuté directement. Un Gunicorn synchrone classique ne peut pas servir une application ASGI tel quel.

Une fois installé, Gunicorn est généralement exécuté derrière un reverse proxy et géré par un superviseur de processus en production — une configuration qu'il est facile de mal régler sans s'en rendre compte. Dans le cadre de mon travail, je conçois et déploie des backends Django ; si vous avez besoin d'aide pour votre backend ou votre infrastructure, découvrez les services de Netalith ou contactez-moi sur LinkedIn.