Comprendre requirements.txt

requirements.txt liste les paquets Python dont votre application a besoin. Sans versions précises, deux installations à deux dates différentes peuvent produire des environnements différents, et un déploiement qui marchait hier échoue aujourd'hui. Le fichier est court, mais sa syntaxe et la façon de l'épingler méritent d'être comprises.

Syntaxe

Flask==3.0.3
requests==2.32.3
gunicorn==22.0.0
uvicorn[standard]==0.30.6

• == fixe une version exacte.
• ~= accepte les correctifs compatibles (~=3.0.2).
• >= seul laisse entrer une future majeure : à éviter en production.
• [standard] installe des dépendances optionnelles.
• ; python_version < "3.12" conditionne l'installation selon l'interpréteur.

Une ligne par paquet, sans virgule finale. Les commentaires commencent par #. Les URL directes et les dépôts Git fonctionnent mais compliquent la reproductibilité et l'audit.

Installer et reproduire

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pip check

pip check signale les dépendances incompatibles. Pour capturer l'arbre complet après installation :

pip freeze > requirements.txt

pip freeze inclut les dépendances transitives, ce qui est utile pour une application déployée. Pour une bibliothèque, préférez un fichier de contraintes ou pip-tools, qui sépare les intentions (requirements.in) des versions résolues.

Sur l'hébergement d'applications, la plateforme exécute l'installation des dépendances avant le démarrage. Un échec apparaît dans la console : version inexistante, paquet nécessitant une compilation, ou incompatibilité avec le Python choisi (3.12, 3.11, 3.10, 3.9).

Mettre à jour sans casser

1. Mettez à jour un paquet à la fois.
2. Lisez le changelog, surtout pour une majeure.
3. Recréez un environnement propre et réinstallez depuis le fichier.
4. Testez l'application, pas seulement import.
5. Commitez le fichier et notez la raison du changement.

Une version retirée du dépôt peut faire échouer une réinstallation alors que l'application tourne encore. Gardez une copie des roues si votre projet est critique, ou épinglez une version disponible et testée.

Bonnes pratiques

• Séparez requirements.txt (runtime) et requirements-dev.txt (tests, formatage).
• Ne versionnez pas .venv.
• N'écrivez jamais de jeton dans une URL de dépôt privé : utilisez une variable d'environnement ou un fichier de configuration non commité.
• Gardez le fichier trié pour rendre les différences lisibles.

Vérifier

Après installation, démarrez l'application et vérifiez la version réellement chargée :

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

Puis testez une route ou une commande qui utilise le paquet. Si l'installation passe mais que l'application échoue, le problème est souvent une dépendance native compilée pour une autre version de Python, pas le fichier lui-même.