Environnements virtuels Python : isoler vos projets

Vous travaillez sur deux projets Python : l’un utilise Django 3.2, l’autre Django 4.2. Sans isolation, installer la nouvelle version écraserait l’ancienne et casserait votre premier projet. Les environnements virtuels résolvent ce problème en créant un espace isolé pour chaque projet, avec ses propres versions de packages.

Un environnement virtuel est un dossier contenant une copie de Python et un espace dédié pour les packages. Quand vous l’activez, toutes les commandes pip install n’affectent que cet environnement — votre système reste intact, vos autres projets aussi.

Ce guide vous montre comment créer, utiliser et gérer des environnements virtuels avec venv (l’outil intégré à Python), puis explore les alternatives comme pipenv et uv.

Analogie simple

Un environnement virtuel, c’est comme une boîte à outils dédiée pour chaque chantier. Le menuisier et l’électricien ont chacun leurs propres outils adaptés à leur travail. Si on mélangeait tout dans une seule boîte, on ne s’y retrouverait plus. L’environnement virtuel isole les “outils” (packages Python) de chaque projet.

Ce que vous allez apprendre

Ce guide couvre tout le cycle de vie des environnements virtuels Python. Chaque section est accompagnée de commandes que vous pouvez exécuter immédiatement.

À la fin de ce guide, vous saurez :

• Comprendre le problème des conflits de dépendances et pourquoi l’isolation est nécessaire
• Créer un environnement virtuel avec venv en une commande
• Activer et désactiver l’environnement selon votre système d’exploitation
• Installer des packages de manière isolée avec pip
• Gérer les dépendances avec requirements.txt pour des environnements reproductibles
• Choisir la bonne alternative entre venv, virtualenv, pipenv et uv

Pourquoi utiliser un environnement virtuel ?

Le problème des conflits de dépendances

Sans environnement virtuel, tous vos projets Python partagent les mêmes packages installés globalement. Voici ce qui peut mal tourner :

Situation	Problème	Conséquence
Projet A utilise requests==2.25	Projet B a besoin de requests==2.31	L’un des deux projets casse
Vous testez une nouvelle version de Flask	L’ancien projet n’est plus compatible	Régression en production
Vous collaborez avec un collègue	Ses versions diffèrent des vôtres	”Ça marche sur ma machine”
Vous déployez en production	Le serveur a d’autres versions	Erreurs imprévisibles

Glissez pour voir

La solution : l’isolation

Avec un environnement virtuel, chaque projet a son propre espace :

Avantages concrets :

• Pas de conflits — chaque projet a ses propres versions de packages
• Reproductibilité — exportez requirements.txt et recréez l’environnement identique ailleurs
• Sécurité — tester une nouvelle version ne risque pas de casser d’autres projets
• Propreté — supprimez un projet = supprimez son environnement, rien ne traîne

Quand utiliser un environnement virtuel ?

Toujours. Même pour un petit script de test. C’est une habitude qui prend 10 secondes et évite des heures de débogage. La seule exception : les outils CLI globaux (installés avec pipx).

Créer un environnement virtuel avec venv

Le module venv est intégré à Python depuis la version 3.3. Pas besoin d’installer quoi que ce soit.

Étape 1 : Vérifier Python

Avant de commencer, vérifiez que Python 3.3+ est installé :

python3 --version

Sortie attendue : Python 3.11.6 (ou version supérieure)

Python 2 vs Python 3

Sur certains systèmes, python pointe vers Python 2. Utilisez toujours python3 explicitement, ou vérifiez avec python --version.

Étape 2 : Créer l’environnement

Dans le dossier de votre projet, exécutez :

python3 -m venv .venv

Cette commande crée un dossier .venv contenant :

Dossier/Fichier	Contenu
bin/ (Linux/macOS) ou Scripts/ (Windows)	Exécutables Python et scripts d’activation
lib/	Packages installés dans cet environnement
include/	Fichiers d’en-tête pour les extensions C
pyvenv.cfg	Configuration de l’environnement

Glissez pour voir

Convention de nommage

Utilisez .venv (avec le point) plutôt que venv ou mon_env. Le point le rend caché sur Linux/macOS et la plupart des .gitignore l’excluent déjà par défaut.

Étape 3 : Vérifier la création

Listez le contenu du dossier créé :

ls -la .venv/

Vous devez voir les dossiers bin/, lib/, include/ et le fichier pyvenv.cfg.

Activer l’environnement virtuel

Créer l’environnement ne l’active pas automatiquement. L’activation modifie votre terminal pour utiliser le Python de l’environnement au lieu du Python global.

Commandes d’activation par système

Linux / macOS

source .venv/bin/activate

Alternative avec point :

. .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\Activate.ps1

Si vous avez une erreur de politique d’exécution :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows (cmd)

.venv\Scripts\activate.bat

Comment savoir si l’environnement est actif ?

Après activation, votre prompt change pour afficher le nom de l’environnement :

# Avant activation
user@machine:~/mon-projet$

# Après activation
(.venv) user@machine:~/mon-projet$

Vérification supplémentaire : la commande which python (Linux/macOS) ou where python (Windows) doit pointer vers .venv/bin/python :

/home/user/mon-projet/.venv/bin/python

which python

L'activation est locale au terminal

L’activation ne concerne que le terminal actuel. Si vous ouvrez un nouveau terminal, vous devez réactiver l’environnement. Chaque session est indépendante.

Désactiver l’environnement

Quand vous avez terminé de travailler sur le projet :

deactivate

Le prompt redevient normal et les commandes python et pip utilisent à nouveau l’installation globale.

Installer des packages avec pip

Une fois l’environnement activé, pip installe les packages uniquement dans cet environnement.

Installer un package

pip install requests

Cette commande :

1. Télécharge le package requests depuis PyPI
2. L’installe dans .venv/lib/python3.x/site-packages/
3. Installe automatiquement ses dépendances (urllib3, certifi, etc.)

Installer une version spécifique

Pour garantir la compatibilité, spécifiez une version exacte :

pip install requests==2.31.0

Syntaxes de version disponibles :

Syntaxe	Signification
requests==2.31.0	Version exacte
requests>=2.28.0	Version minimale
requests>=2.28,<3.0	Plage de versions
requests~=2.31.0	Compatible avec 2.31.x

Glissez pour voir

Lister les packages installés

pip list

Sortie exemple :

Package            Version
------------------ ---------
certifi            2023.11.17
charset-normalizer 3.3.2
idna               3.6
pip                23.3.1
requests           2.31.0
urllib3            2.1.0

Mettre à jour un package

pip install --upgrade requests

Désinstaller un package

pip uninstall requests

Confirmez avec y quand demandé.

Voir les dépendances d'un package

Pour comprendre pourquoi un package est installé :

pip show requests

Affiche les métadonnées incluant Requires: (dépendances) et Required-by: (qui en dépend).

Gérer les dépendances avec requirements.txt

Le fichier requirements.txt liste toutes les dépendances de votre projet. Il permet de recréer un environnement identique sur une autre machine.

Exporter les dépendances actuelles

pip freeze > requirements.txt

Contenu généré :

certifi==2023.11.17
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.1.0

Installer depuis requirements.txt

Sur une nouvelle machine ou après avoir cloné un projet :

1. Créer un environnement virtuel

   python3 -m venv .venv

2. Activer l’environnement

   source .venv/bin/activate

3. Installer les dépendances

   pip install -r requirements.txt

Toutes les dépendances sont installées avec les versions exactes spécifiées.

Bonnes pratiques pour requirements.txt

1. Séparez les dépendances directes des indirectes

Créez deux fichiers :

• requirements.in — packages que vous utilisez directement
• requirements.txt — généré par pip freeze, inclut les dépendances transitives

2. Versionnez requirements.txt dans Git

git add requirements.txt
git commit -m "Ajout des dépendances du projet"

3. Gardez les versions à jour

Périodiquement, vérifiez les mises à jour de sécurité :

pip list --outdated

pip freeze inclut tout

pip freeze liste tous les packages, y compris ceux installés par erreur ou pour des tests. Avant de commit, vérifiez que la liste correspond bien à vos besoins réels.

Supprimer un environnement virtuel

Un environnement virtuel est un simple dossier. Pour le supprimer :

Linux / macOS

rm -rf .venv

Windows

rmdir /s /q .venv

Avant de supprimer

Exportez vos dépendances si vous ne l’avez pas fait :

pip freeze > requirements.txt

Vous pourrez recréer l’environnement plus tard.

Structure d’un projet Python typique

Voici comment organiser un projet Python avec environnement virtuel :

mon-projet/
├── .venv/                  # Environnement virtuel (exclu de Git)
├── .gitignore              # Inclut .venv/
├── requirements.txt        # Dépendances
├── src/                    # Code source
│   ├── __init__.py
│   └── main.py
├── tests/                  # Tests
│   └── test_main.py
└── README.md

Contenu minimal de .gitignore :

# Environnement virtuel
.venv/
venv/
env/

# Cache Python
__pycache__/
*.pyc
*.pyo

# pip
pip-log.txt

Alternatives à venv

venv convient à la majorité des projets, mais d’autres outils offrent des fonctionnalités supplémentaires.

Comparatif des outils

Outil	Points forts	Cas d’usage
venv	Intégré à Python, simple	Projets standards
virtualenv	Compatible Python 2, plus rapide	Legacy, CI/CD
pipenv	Pipfile.lock, gestion intégrée	Équipes, reproductibilité
uv	Ultra-rapide (Rust), compatible pip	Projets modernes, CI/CD
conda	Packages non-Python, data science	ML, calcul scientifique

Glissez pour voir

virtualenv

Plus ancien que venv, mais supporte Python 2 et crée les environnements plus rapidement.

pip install virtualenv
virtualenv .venv
source .venv/bin/activate

pipenv

Combine environnement virtuel et gestion des dépendances dans un seul outil. Utilise Pipfile au lieu de requirements.txt.

pip install pipenv
pipenv install requests    # Crée l'env et installe le package
pipenv shell               # Active l'environnement

Fichiers générés :

• Pipfile — dépendances lisibles
• Pipfile.lock — versions exactes verrouillées

uv (recommandé pour les nouveaux projets)

Outil moderne écrit en Rust, 10 à 100 fois plus rapide que pip pour l’installation de packages.

# Installation de uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Créer un environnement et installer des packages
uv venv
source .venv/bin/activate
uv pip install requests

Avantages de uv :

• Compatible avec requirements.txt et pyproject.toml
• Résolution de dépendances déterministe
• Cache global partagé entre projets

Quel outil choisir ?

• Débutant ou projet simple → venv (rien à installer)
• Équipe avec besoins de reproductibilité → pipenv ou uv
• CI/CD avec beaucoup de packages → uv (performance)
• Data science avec packages système → conda

pipx : installer des outils CLI globaux

Certains outils Python sont des CLI globaux (black, flake8, httpie…) que vous voulez utiliser partout, pas dans un projet spécifique.

Problème : les installer avec pip globalement peut créer des conflits.

Solution : pipx installe chaque outil dans son propre environnement isolé, tout en rendant la commande disponible globalement.

# Installer pipx
pip install pipx
pipx ensurepath

# Installer des outils globaux isolés
pipx install black
pipx install httpie
pipx install poetry

# Utiliser l'outil n'importe où
black --version
http https://api.github.com

Dépannage

L’environnement ne s’active pas

Symptôme	Cause probable	Solution
source: not found	Shell non compatible	Utilisez bash ou . .venv/bin/activate
Erreur PowerShell	Politique d’exécution	Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Pas de changement de prompt	Activation échouée silencieusement	Vérifiez que .venv/bin/activate existe

Glissez pour voir

pip installe globalement malgré l’activation

/chemin/vers/.venv/bin/pip

# Vérifier quel pip est utilisé
which pip
# Si ce n'est pas le cas, utilisez explicitement
.venv/bin/pip install requests

Conflit de versions lors de l’installation

# Voir les dépendances en conflit
pip check

# Forcer la réinstallation des dépendances
pip install --force-reinstall -r requirements.txt

L’environnement est corrompu

Parfois, après une mise à jour de Python système, l’environnement ne fonctionne plus :

# Solution : recréer l'environnement
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

À retenir

Si vous ne retenez que six choses de ce guide, retenez celles-ci :

1. Toujours utiliser un environnement virtuel — même pour un petit projet. C’est 10 secondes qui évitent des heures de débogage.

2. Convention .venv — nommez votre environnement .venv dans le dossier du projet, il sera automatiquement ignoré par Git.

3. Activer avant d’installer — vérifiez que (.venv) apparaît dans votre prompt avant tout pip install.

4. requirements.txt pour la reproductibilité — exportez avec pip freeze > requirements.txt et versionnez ce fichier.

5. deactivate pour sortir — simple mais souvent oublié. Votre prompt redevient normal.

6. Supprimer = supprimer le dossier — pas de désinstallation complexe, juste rm -rf .venv.

Checklist

Utilisez cette checklist pour valider votre maîtrise des environnements virtuels :

Bases

• Créer un environnement avec python3 -m venv .venv
• Activer l’environnement (Linux/macOS/Windows)
• Vérifier l’activation avec which python
• Désactiver avec deactivate

Gestion des packages

• Installer un package avec pip install
• Installer une version spécifique
• Lister les packages installés avec pip list
• Exporter avec pip freeze > requirements.txt
• Installer depuis pip install -r requirements.txt

Avancé

• Supprimer proprement un environnement
• Configurer .gitignore correctement
• Utiliser pipx pour les outils CLI globaux
• Connaître les alternatives (pipenv, uv)

Prochaines étapes

Débuter avec Python Si vous débutez, commencez par les bases du langage Python.

Modules et packages Organisez votre code en modules et créez vos propres packages.

Qualité du code Python Configurez les outils de linting et formatage dans votre environnement.

Manipulation JSON Apprenez à lire et écrire des fichiers JSON avec Python.

×

📖 Voir la documentation →