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.

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

La mise à jour d'un package installe la dernière version disponible sur PyPI compatible avec votre version de Python, sans demander de confirmation. Elle touche aussi les dépendances transitives si la nouvelle version en exige d'autres. Sur un projet dont le requirements.txt est versionné, régénérez ce fichier juste après, sinon votre environnement local et celui de vos collègues divergent silencieusement.

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

Lisez ce tableau par la colonne Cas d'usage plutôt que par les points forts : ces outils ne se remplacent pas les uns les autres, ils répondent à des contraintes différentes. La ligne conda est à part, c'est le seul de la liste qui installe aussi des bibliothèques système non Python (BLAS, CUDA, GDAL), ce que pip ne sait pas faire. Les quatre autres se limitent aux paquets Python et diffèrent surtout par la vitesse d'installation et par le format de verrouillage des versions.

Outil	Points forts	Cas d'usage
venv	Intégré à Python, simple	Projets standards
virtualenv	Création plus rapide, options avancées	CI/CD, projets multi-interpréteurs
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, dont il est l'ancêtre direct, virtualenv crée les environnements plus vite parce qu'il embarque une copie de pip au lieu de la reconstruire à chaque fois. Attention à une idée reçue tenace : virtualenv ne crée plus d'environnements Python 2 depuis la version 20.22.0 d'avril 2023, et depuis la 21.5.0 de juin 2026 il exige un interpréteur Python 3.9 ou supérieur, aussi bien pour tourner que pour la cible. Si vous devez encore servir du Python 2, il vous faut une ancienne version figée de virtualenv.

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, annoncé par son éditeur Astral comme 10 à 100 fois plus rapide que pip pour l'installation de packages. L'installation ci-dessous récupère l'archive binaire publiée sur GitHub et le fichier d'empreinte associé, puis refuse de continuer si les deux ne concordent pas. La commande sha256sum --check doit répondre OK ; toute autre réponse signifie que l'archive a été altérée ou tronquée, n'extrayez rien dans ce cas.

# Installation de uv par archive vérifiée (version testée : 0.11.31)
UV_VERSION=0.11.31
BASE="https://github.com/astral-sh/uv/releases/download/${UV_VERSION}"
curl -sSLO "${BASE}/uv-x86_64-unknown-linux-gnu.tar.gz"
curl -sSLO "${BASE}/uv-x86_64-unknown-linux-gnu.tar.gz.sha256"
sha256sum --check uv-x86_64-unknown-linux-gnu.tar.gz.sha256
tar -xzf uv-x86_64-unknown-linux-gnu.tar.gz
install -m 0755 uv-x86_64-unknown-linux-gnu/uv ~/.local/bin/uv

# 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.

Un détail d'installation piège les lecteurs sous Debian 12+, Ubuntu 23.04+ et Fedora récentes : ces distributions marquent leur Python système comme externally managed (fichier /usr/lib/python3.X/EXTERNALLY-MANAGED, défini par la PEP 668), et pip install hors environnement virtuel y échoue avec error: externally-managed-environment. Passez donc par le paquet de la distribution.

# Installer pipx (Debian / Ubuntu récents : le paquet système est la voie officielle)
sudo apt install pipx
# Ailleurs, ou si le paquet n'existe pas :
# python3 -m pip install --user 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

Le script d'activation ne fait qu'une chose : modifier des variables du shell courant, dont PATH et VIRTUAL_ENV. C'est pour cela que la troisième ligne du tableau est trompeuse, un script d'activation lancé comme un programme (./activate au lieu de source) s'exécute dans un sous-shell qui disparaît aussitôt, sans erreur visible et sans effet. Vérifiez donc d'abord comment vous appelez le script avant de soupçonner l'environnement lui-même.

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

Deux causes couvrent la quasi-totalité des cas. La première est l'usage de sudo, qui remplace votre PATH par le secure_path défini dans /etc/sudoers : sudo pip install ignore donc systématiquement l'environnement actif et écrit dans les paquets système. La seconde est un environnement déplacé ou renommé. Le lanceur .venv/bin/pip est un script dont le shebang contient le chemin absolu de l'interpréteur, figé à la création ; déplacer le dossier du projet rend ce chemin invalide et produit un cannot execute: required file not found. Dans ce cas, recréez l'environnement, il n'est pas réparable. Le contrôle par le chemin complet ci-dessous distingue les deux situations sans dépendre du PATH.

/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

pip check ne s'exécute pas pendant l'installation, il relit après coup les métadonnées des paquets déjà présents et signale les exigences non satisfaites. C'est utile parce que pip install accepte de casser une dépendance existante : il affiche bien une ligne ERROR: pip's dependency resolver does not currently take into account all the packages that are installed, mais termine quand même par Successfully installed et rend le code de retour 0. Un pipeline CI qui se fie au seul code de retour ne voit donc rien. Lancez donc pip check après chaque série d'installations : une sortie No broken requirements found. est le seul résultat acceptable avant de figer un requirements.txt.

# 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

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À 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

Ces quatre gestes forment le cycle complet d'un environnement. Faites-les dans l'ordre sur un dossier vide : si which python renvoie encore le Python système après activation, arrêtez-vous là, tout ce qui suit dans ce guide reposerait sur une activation qui n'a pas pris.

• 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

Le point qui fait vraiment la différence est l'avant-dernier. Tant que vous n'avez pas rejoué pip install -r requirements.txt dans un environnement neuf, vous ne savez pas si votre fichier de dépendances est complet ; un paquet installé à la main et oublié dans l'export ne se manifeste qu'au moment où un collègue clone le projet.

• 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é

Ces quatre points relèvent de l'hygiène du projet plutôt que de son fonctionnement. Le troisième est celui qu'on saute le plus souvent : installer un outil de ligne de commande comme black ou httpie avec pip dans le projet le rend indisponible ailleurs et l'ajoute au requirements.txt alors qu'il ne fait pas partie des dépendances de l'application. pipx sépare les deux usages.

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

Pour aller plus loin

• Qualité du code Python : configurez les outils de linting et de formatage dans votre environnement.

×

📖 Voir la documentation →