Python : un environnement virtuel propre en trois commandes

Installer des paquets Python « dans le système » avec sudo pip install, c'est s'exposer à deux ennuis : casser des outils de la distribution qui dépendent de versions précises, et voir deux projets réclamer des versions incompatibles de la même bibliothèque. Debian, Ubuntu et plusieurs autres distributions l'interdisent d'ailleurs désormais (erreur externally-managed-environment).

La réponse tient en un réflexe : un environnement virtuel par projet.

Les trois commandes

Depuis la racine du projet :

$ python3.12 -m venv .venv
$ source .venv/bin/activate
(.venv) $ pip install fastapi sqlalchemy

1. python3.12 -m venv .venv crée un dossier .venv contenant un interpréteur et un pip propres au projet. Choisir explicitement la version (python3.12) évite les surprises si plusieurs versions sont installées.
2. source .venv/bin/activate active l'environnement : python et pip pointent désormais vers ceux du projet, et l'invite du terminal l'indique.
3. pip install … installe dans .venv, et nulle part ailleurs. Pas de sudo. Pour vérifier qu'on utilise bien le bon interpréteur :

(.venv) $ which python
/home/marc/projets/mon-projet/.venv/bin/python

Et pour quitter l'environnement : deactivate.

Figer les dépendances

Pour pouvoir recréer l'environnement à l'identique, sur un autre poste ou sur le serveur de production :

pip freeze > requirements.txt

Et de l'autre côté :

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

Sur un projet un peu structuré, on déclare plutôt les dépendances dans un pyproject.toml et on installe le projet lui-même avec pip install -e .. Le principe reste le même : l'environnement se reconstruit, il ne se copie pas.

Ce qui reste hors de Git

Le dossier .venv ne se versionne jamais : il pèse lourd, et il contient des chemins absolus propres à votre machine. On versionne la liste des dépendances, pas les dépendances.

echo ".venv/" >> .gitignore

Quelques pièges

• Un environnement virtuel ne se déplace pas. Ses scripts contiennent le chemin complet du dossier : si vous renommez ou déplacez le projet, supprimez .venv et recréez-le. Ça prend dix secondes.
• python3.12: command not found : la version n'est pas installée. Sous Fedora, qui fournit une version plus récente par défaut, les versions antérieures s'installent à côté sans rien casser : sudo dnf install python3.12.
• Mettre pip à jour dans l'environnement fait disparaître bien des messages d'avertissement :

  python -m pip install --upgrade pip

• Les IDE le gèrent très bien. PyCharm détecte un .venv à la racine du projet et l'utilise comme interpréteur. Encore faut-il qu'il existe : c'est l'objet des trois commandes ci-dessus.