Environnements virtuels Python : venv, activation et requirements.txt

Le problème que les environnements virtuels résolvent

Installe Python, lance pip install requests, et le package atterrit dans un seul endroit global. Ça marche pour un projet. Au troisième projet, ça commence à faire mal :

• Le projet A a besoin de django==3.2. Le projet B a besoin de django==5.0. Un seul des deux peut avoir sa version installée globalement.
• Tu veux essayer une nouvelle bibliothèque mais ne veux pas qu'elle pollue tous les autres projets de ta machine.
• Un coéquipier clone ton repo et n'a aucune idée de quelles versions de quels packages tu dépendais vraiment.

Un environnement virtuel est le correctif. C'est un dossier autonome qui contient un interpréteur Python et son propre répertoire d'installation de bibliothèques. Quand l'environnement est activé, python et pip dans ton terminal pointent à l'intérieur de ce dossier au lieu de ton Python global. Les packages installés là restent là.

Créer un avec venv

venv est livré avec Python 3 — rien à installer. Depuis ton répertoire de projet :

python3 -m venv .venv

Ça crée un dossier .venv/ à côté de ton code. Le nom .venv est une convention quasi universelle ; le point au début le garde hors de la plupart des listings de répertoires, et les éditeurs comme VS Code le détectent automatiquement.

Quand la commande se termine, le dossier contient une installation Python complète (des dizaines de mégaoctets, ce qui est normal) et un pip à lui.

Activer l'environnement

L'activation réécrit le PATH de ton shell pour que python et pip résolvent vers ceux à l'intérieur de .venv/. La commande dépend de ta plateforme :

# macOS / Linux
source .venv/bin/activate

# Windows (Invite de commandes)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Ton prompt reçoit un préfixe (.venv) tant que l'environnement est actif — un rappel visuel. Tout pip install que tu lances maintenant n'affecte que ce projet.

Quand tu as fini pour la journée, deactivate restaure l'état précédent :

deactivate

Tu n'as pas besoin de désactiver avant de fermer le terminal — quitter le shell, c'est la même chose.

Installer des packages

Avec l'environnement actif, installe ce dont tu as besoin :

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Vérifie ce qui est installé avec pip list. Retire quelque chose avec pip uninstall requests.

Les packages installés vivent sous .venv/lib/pythonX.Y/site-packages/. Tu n'édites jamais ceux-là à la main — pip gère le répertoire.

Épingler les dépendances avec requirements.txt

Ton projet n'est reproductible que si les autres peuvent installer les mêmes versions que tu as utilisées. La façon la plus simple de capturer ça, c'est requirements.txt :

pip freeze > requirements.txt

pip freeze affiche chaque package installé avec sa version exacte. Commite le fichier dans git.

Quand un collaborateur (ou toi plus tard sur une nouvelle machine) clone le repo :

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

Trois commandes et leur environnement correspond au tien.

Une configuration de projet courante

Le workflow complet, du début à la fin :

# Crée le dossier de projet
mkdir my_tool && cd my_tool

# Crée et active le venv
python3 -m venv .venv
source .venv/bin/activate

# Installe les dépendances
pip install requests rich

# Enregistre-les
pip freeze > requirements.txt

# Travaille sur ton code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# Quand tu as fini
deactivate

Ajoute .venv à ton .gitignore

Ne commite jamais le dossier .venv/. Il est spécifique à la plateforme et reproductible depuis requirements.txt :

# .gitignore
.venv/
__pycache__/
*.pyc

Le commiter gonflerait le repo, casserait sur d'autres machines et fuirait les binaires spécifiques à l'OS que ton interpréteur a.

Quelle version de Python ?

Par défaut, python3 -m venv .venv utilise le python3 que ton shell résout. Si tu as plusieurs Pythons installés (disons 3.12 et 3.13), sois explicite sur lequel :

python3.13 -m venv .venv

Une fois que le venv existe, son interpréteur est épinglé — exécuter python dans le venv activé utilise toujours cette version spécifique, même si ton Python système change.

Quand quelque chose cloche

Quelques symptômes courants et leurs correctifs :

• pip install marche, mais mes imports échouent. Tu as installé contre le mauvais Python. Active le venv avant pip install, et revérifie avec which python (macOS/Linux) ou where python (Windows).
• « ModuleNotFoundError » après activation. Le venv a été créé sans certaines bibliothèques, ou le package est installé dans un venv différent. pip list montre ce qui est vraiment dans le courant.
• Script d'activation introuvable sur Windows. PowerShell peut bloquer les scripts non signés. Lance Set-ExecutionPolicy -Scope CurrentUser RemoteSigned une fois pour autoriser les scripts locaux.
• « No module named venv ». Sur certaines distributions Linux, venv est un paquet séparé. sudo apt install python3-venv sur Debian/Ubuntu.

Au-delà de venv : Poetry, uv, pipenv

Une fois à l'aise avec venv + pip + requirements.txt, tu croiseras des outils qui enveloppent les mêmes idées avec une meilleure ergonomie :

• Poetry — gère venvs, dépendances et packaging avec un seul pyproject.toml.
• uv — un remplacement drop-in très rapide pour pip ; gère aussi les venvs.
• pipenv — un outil plus ancien qui a popularisé le motif « Pipfile + Pipfile.lock ».

Tous sont bons. Aucun n'est nécessaire pour apprendre. Sois à l'aise avec le workflow venv basique d'abord ; le reste sont des optimisations.

Ce qu'il faut retenir

• Chaque vrai projet Python a son propre environnement virtuel.
• Crée-en un avec python3 -m venv .venv, active-le, puis pip install librement.
• Épingle les dépendances avec pip freeze > requirements.txt et commite ce fichier.
• Ne commite jamais le dossier .venv/ lui-même.
• Quand les imports se comportent mal, vérifie d'abord quel Python est actif.

Ensuite : le motif __main__

Avec un projet configuré et des packages installés, un dernier idiome clôt ce chapitre — la garde if __name__ == "__main__". Elle est dans presque chaque fichier Python destiné à être lancé comme script, et c'est le sujet de la prochaine page.