Environnements virtuels Python (venv)

Un environnement virtuel est un répertoire autonome qui contient une copie privée d'un interpréteur Python ainsi que son propre dossier site-packages. Les paquets installés à l'intérieur d'un environnement virtuel sont complètement isolés de votre Python système et de tous les autres environnements présents sur votre machine — ainsi, deux projets peuvent dépendre de versions différentes d'une même bibliothèque sans jamais entrer en conflit.

Ce chapitre explique pourquoi les environnements virtuels sont importants, comment les créer et les activer avec le module intégré venv, comment gérer les dépendances avec pip, et le workflow quotidien que suivent la plupart des projets Python.

Pourquoi les environnements virtuels sont importants

Imaginez que vous avez deux projets sur la même machine :

• Projet A nécessite requests==2.28.0
• Projet B nécessite requests==2.31.0

Si vous installez les deux versions dans l'environnement Python global, pip écrase simplement la version installée en premier. L'un des projets sera cassé. Les environnements virtuels résolvent ce problème en donnant à chaque projet son propre répertoire site-packages isolé, de sorte que les deux versions coexistent sans se toucher.

Autres avantages pratiques :

Créer un environnement virtuel

Python 3.3 et les versions ultérieures incluent venv dans la bibliothèque standard — aucune installation n'est nécessaire.

python -m venv .venv

Cela crée un répertoire .venv dans votre dossier actuel. Le nom .venv est une convention courante (le point initial le masque sur les systèmes de type Unix), mais vous pouvez utiliser n'importe quel nom — env, venv, ou même un nom spécifique au projet.

Ce que venv crée à l'intérieur de .venv :

.venv/
├── bin/           # Python interpreter + activation scripts (Linux/macOS)
│   ├── activate
│   ├── python -> python3
│   └── pip
├── include/
├── lib/
│   └── python3.x/
│       └── site-packages/   # Installed packages go here
└── pyvenv.cfg               # Records the Python version and base prefix

Sur Windows, la disposition diffère légèrement — bin/ devient Scripts/ et les séparateurs de chemin sont des barres obliques inverses.

Choisir une version spécifique de Python

Si vous avez plusieurs versions de Python installées, passez l'interpréteur explicitement :

python3.11 -m venv .venv

Ou sur Windows :

py -3.11 -m venv .venv

Le fichier pyvenv.cfg à l'intérieur de l'environnement enregistre quel interpréteur a été utilisé, de sorte que l'environnement s'exécute toujours avec cette version.

Activer l'environnement

La création de l'environnement ne l'utilise pas automatiquement. Vous devez l'activer, ce qui ajoute le répertoire bin/ de l'environnement au début de votre PATH afin que python et pip pointent vers les copies de l'environnement.

macOS et Linux :

source .venv/bin/activate

Windows (Invite de commandes) :

.venv\Scripts\activate.bat

Windows (PowerShell) :

.venv\Scripts\Activate.ps1

Après l'activation, votre invite de commande affiche généralement le nom de l'environnement entre parenthèses :

(.venv) $ python --version
Python 3.12.3
(.venv) $ which python
/your/project/.venv/bin/python

Chaque commande pip install exécutée pendant que l'environnement est actif installe dans .venv/lib/.../site-packages/, jamais dans le Python système.

Désactiver

Lorsque vous avez terminé de travailler sur le projet, ou si vous souhaitez passer à un autre environnement :

deactivate

Votre invite de commande retrouve son apparence normale et python pointe à nouveau vers l'interpréteur système.

Installer des paquets dans un environnement virtuel

Avec l'environnement actif, utilisez pip normalement :

pip install requests flask

Vérifiez que les paquets ont été installés au bon endroit :

pip show requests

La ligne Location: dans la sortie doit pointer vers votre répertoire .venv.

Vérifier ce qui est installé

pip list

Un environnement fraîchement créé contient généralement seulement pip et setuptools. Tout le reste que vous voyez est quelque chose que vous (ou un fichier requirements) avez installé explicitement.

Sauvegarder et restaurer les dépendances

Exporter un fichier requirements

Une fois votre environnement configuré, figez les versions exactes des paquets pour que n'importe qui puisse le reproduire :

pip freeze > requirements.txt

Un fichier requirements.txt typique ressemble à ceci :

certifi==2024.2.2
charset-normalizer==3.3.2
flask==3.0.3
idna==3.6
requests==2.31.0
urllib3==2.2.1

Soumettez requirements.txt au contrôle de version. Ne soumettez pas le répertoire .venv lui-même — ajoutez-le à .gitignore.

Restaurer depuis un fichier requirements

Sur une nouvelle machine ou dans un clone fraîchement récupéré :

python -m venv .venv
source .venv/bin/activate        # or the Windows equivalent
pip install -r requirements.txt

Cela recrée un environnement identique à celui que vous avez figé.

Workflow standard pour un projet

La plupart des projets Python suivent cette séquence :

# 1. Clone the repository
git clone https://github.com/example/myproject.git
cd myproject

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
source .venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Work on the project ...

# 6. When you add a new package, update the requirements file
pip install newpackage
pip freeze > requirements.txt

Ce qu'il faut ajouter à .gitignore

Ne soumettez jamais le répertoire de l'environnement au contrôle de version — il contient des binaires compilés, est spécifique à la plateforme, et peut peser des dizaines de mégaoctets. Ajoutez l'un de ces motifs à votre .gitignore :

# Virtual environment
.venv/
venv/
env/

Ne soumettez que requirements.txt (ou pyproject.toml + requirements.txt). C'est tout ce dont quelqu'un a besoin pour reconstruire l'environnement depuis zéro.

venv versus les autres outils

venv est la solution intégrée et suffit pour la plupart des cas d'usage. Vous pouvez aussi rencontrer ces alternatives :

Pour la plupart des débutants et des projets simples, python -m venv est le bon choix — il est livré avec Python et ne nécessite aucune installation supplémentaire.

Erreurs courantes et solutions

« python: command not found » lors de la création de l'environnement

Sur certaines distributions Linux, Python 3 est invoqué avec python3, pas python :

python3 -m venv .venv

PowerShell refuse d'exécuter le script d'activation

Par défaut, Windows PowerShell bloque les scripts non signés. Activez l'exécution de scripts pour l'utilisateur actuel :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Puis relancez le script d'activation.

Les paquets sont installés mais import échoue

Vous avez probablement oublié d'activer l'environnement. Exécutez :

source .venv/bin/activate

Puis réessayez l'import. Vous pouvez vérifier quel Python est actif avec which python (macOS/Linux) ou where python (Windows).

L'environnement fait référence à une installation Python supprimée

Si vous mettez à niveau Python et supprimez l'ancienne version, les liens venv sont cassés. Recréez simplement l'environnement :

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Tableau de référence rapide

Chapitres connexes

• Python pip — le guide complet pour installer, mettre à jour et supprimer des paquets
• Python Modules — comprendre le fonctionnement du système d'import de Python
• Python Packages — organiser votre propre code en paquets installables

Exercices pratiques