requirements.txt : la liste des dépendances d'un projet Python

Définition

Vous récupérez un projet Python jamais installé, et rien ne fonctionne au premier lancement : des bibliothèques manquent, sans que rien ne dise lesquelles. requirements.txt répond à cet ennui en énumérant, une par ligne, ce dont le projet a besoin. Il ne contient aucun code et Python ne le lit jamais : c'est pip qui en a fait un standard de fait, en acceptant de l'ouvrir, sans qu'aucune PEP ne le définisse officiellement.

Une ligne vide ne compte pas, ni une ligne qui commence par un croisillon, ce qui laisse la place à un commentaire au-dessus de chaque groupe. Un exemple le montre.

# Dépendances de l'application
requests==2.32.3
flask==3.0.3
pandas==2.2.2

Une seule commande reconstitue l'environnement entier, en allant chercher chaque package sur PyPI.

pip install -r requirements.txt

Le problème qu'il règle

Un dépôt Git conserve le code, jamais les bibliothèques qu'il utilise. Celui qui clone le projet récupère donc des fichiers qui appellent des outils absents de sa machine.

import requests
import pandas as pd
from flask import Flask

# Trois bibliothèques, aucune installée sur une machine neuve

Sans liste écrite, il faut lancer le programme, lire l'erreur, installer la bibliothèque désignée, relancer, et recommencer pour chaque import orphelin. Avec trois bibliothèques, c'est supportable ; avec la trentaine d'une vraie application, c'est un après-midi perdu, que chaque nouveau développeur reperd à son arrivée. Le fichier remplace cette chasse par une commande : le serveur installe la même liste que la machine de développement, et « ça marche chez moi » cesse d'être une explication recevable.

Épingler les versions, ou non

La même bibliothèque, écrite de trois façons différentes, ne produira pas la même installation six mois plus tard. Voici ce que chacune signifie pour pip.

Une application vit seule sur son serveur : elle n'a rien à négocier et peut épingler la version testée. Une bibliothèque, elle, sera installée aux côtés d'autres, choisies par quelqu'un d'autre : exiger une version exacte de chacune de ses dépendances la ferait entrer en conflit avec la moindre autre bibliothèque du projet réclamant une version différente. Elle assouplit donc ses contraintes, et laisse l'application trancher.

pip freeze, et le piège qui l'accompagne

Écrire un fichier de plusieurs dizaines de lignes à la main serait fastidieux, alors pip propose de le faire pour vous.

pip freeze > requirements.txt

Cette commande recopie tout ce qui est installé dans l'environnement courant : sans environnement virtuel actif, elle capture aussi les outils d'autres projets, et produit cent cinquante lignes pour un programme qui en utilise trois. La correction consiste à créer un venv par projet avant d'y installer quoi que ce soit, pas à nettoyer le fichier à la main.

Second effet, plus discret : pip freeze mélange les bibliothèques choisies avec celles qu'elles ont amenées comme dépendances indirectes. Rien ne distingue plus l'une de l'autre, et retirer une bibliothèque plus tard tourne à l'archéologie.

requirements.txt ou pyproject.toml

Le second est le format officiel de description d'un projet Python, et il est tentant de le présenter comme le remplaçant naturel du premier. La réalité mérite d'être plus nuancée.

Le format récent ne rend pas l'ancien obsolète, il répond à un besoin différent : nombre d'hébergeurs et d'images Docker cherchent encore un requirements.txt et rien d'autre. Un script personnel se contente du fichier texte ; une équipe voulant des installations identiques au bit près a besoin du verrouillage.

Ce qu'il ne fait pas

Trois attentes raisonnables se heurtent aux limites du format.

La première concerne la version de Python : le fichier ne dit nulle part laquelle le projet exige, et un requirements.txt épinglé s'installera quand même sur un interpréteur trop ancien, avant que le programme casse plus loin, sur une syntaxe non reconnue.

La deuxième touche à l'environnement virtuel. Le fichier ne le crée pas, il suppose qu'il est déjà actif, ce qui explique la plupart des installations parties par erreur dans le Python du système.

La troisième concerne ce qui n'est pas du Python : une dépendance qui réclame un compilateur ou un client de base de données échouera sur une machine nue. Ces limites sont le prix de sa simplicité.

Questions fréquentes

Oui, c'est toute sa raison d'être : il voyage avec le code et reste lisible par quiconque clone le projet. Ce qui ne doit jamais le suivre, c'est le dossier de l'environnement virtuel, lourd et valable seulement sur la machine qui l'a créé.

Parce qu'une dépendance indirecte n'était pas épinglée, et a publié entre-temps une version incompatible. Le fichier n'a pas changé, mais ce qu'il désigne a changé sous ses pieds : c'est l'argument central en faveur d'une liste figée pour tout ce qui part en production.

En écrivant un second fichier, requirements-dev.txt, dont la première ligne rappelle le premier via l'option -r, avant d'ajouter pytest ou ruff. Le serveur n'installe alors que la liste de production.