Les environnements virtuels Python règlent l’un des problèmes les plus courants du développement Python : les conflits de dépendances entre projets. Quand le projet A a besoin de Django 4.2 et le projet B de Django 5.0, installer les deux en global casse l’un d’eux. Les environnements virtuels créent des installations Python isolées où chaque projet possède ses propres paquets, ses propres versions et son propre pip — complètement indépendants les uns des autres et de votre Python système. Ce guide couvre tout, de la création de votre premier environnement jusqu’aux schémas de déploiement en production.
Prérequis
- Python 3.3 ou version ultérieure installé (
python3 --versionpour vérifier) - Connaissance de base de la ligne de commande (terminal, shell ou PowerShell)
- Un éditeur de texte ou un IDE pour le développement Python
pipdisponible (inclus avec Python 3.4+ par défaut)
Créer des Environnements Virtuels avec venv
venv est le module intégré de Python pour créer des environnements virtuels. Il est livré avec Python 3.3+ et ne nécessite aucune installation supplémentaire.
Création de base
# Créer un environnement virtuel dans le répertoire .venv
python3 -m venv .venv
# Sur certains systèmes, vous devrez peut-être d'abord installer le paquet venv
# Debian/Ubuntu :
sudo apt install python3-venv
# Vérifier que l'environnement a été créé
ls .venv/
# Résultat : bin/ include/ lib/ pyvenv.cfgLe nom de répertoire .venv est une convention — vous pouvez lui donner n’importe quel nom, mais .venv est le choix le plus répandu. Le point initial le cache dans les listings de répertoires Unix et la plupart des modèles .gitignore l’excluent déjà.
Ce que venv crée
.venv/
├── bin/ # Scripts d'activation et exécutables (Linux/macOS)
│ ├── activate # Script d'activation Bash
│ ├── activate.csh # Activation pour C-shell
│ ├── activate.fish # Activation pour Fish shell
│ ├── pip # pip isolé
│ ├── pip3 # Lien symbolique vers pip
│ └── python3 # Lien symbolique vers l'interpréteur Python
├── include/ # En-têtes C pour compiler des extensions
├── lib/python3.x/
│ └── site-packages/ # Où pip installe les paquets
└── pyvenv.cfg # Configuration de l'environnementSous Windows, la structure est similaire mais utilise Scripts/ au lieu de bin/ et des extensions .exe.
Activer l’environnement
L’activation modifie le PATH de votre shell pour que python et pip pointent vers les copies de l’environnement virtuel plutôt que vers les versions système.
# Linux / macOS (Bash/Zsh)
source .venv/bin/activate
# Linux (Fish shell)
source .venv/bin/activate.fish
# Windows (Invite de commandes)
.venv\Scripts\activate.bat
# Windows (PowerShell)
.venv\Scripts\Activate.ps1Une fois activé, votre prompt change pour afficher le nom de l’environnement :
(.venv) user@hostname:~/myproject$Vérifier que l’environnement est actif :
# Vérifier quel Python est utilisé
which python3
# Résultat : /home/user/myproject/.venv/bin/python3
# Vérifier quel pip est utilisé
which pip
# Résultat : /home/user/myproject/.venv/bin/pip
# Le Python système est intact
python3 -c "import sys; print(sys.prefix)"
# Résultat : /home/user/myproject/.venvDésactiver l’environnement
deactivateCela restaure votre PATH à son état précédent. L’environnement virtuel reste sur le disque — la désactivation ne supprime rien.
Gérer les Paquets avec pip
Une fois l’environnement virtuel activé, pip installe les paquets uniquement dans cet environnement.
Installer des paquets
# Installer un paquet spécifique
pip install requests
# Installer une version précise
pip install requests==2.31.0
# Installer avec une contrainte de version
pip install "requests>=2.28,<3.0"
# Installer plusieurs paquets
pip install flask sqlalchemy redis
# Mettre à jour un paquet
pip install --upgrade requests
# Installer depuis un dépôt Git
pip install git+https://github.com/user/repo.git@mainLister et inspecter les paquets
# Lister tous les paquets installés
pip list
# Afficher les informations détaillées d'un paquet
pip show requests
# Vérifier les paquets obsolètes
pip list --outdated
# Afficher l'arbre de dépendances (installer pipdeptree d'abord)
pip install pipdeptree
pipdeptreeDésinstaller des paquets
# Supprimer un paquet
pip uninstall requests
# Supprimer un paquet sans confirmation
pip uninstall -y requestsTravailler avec requirements.txt
requirements.txt est la méthode standard pour déclarer et partager les dépendances d’un projet Python. Il liste les paquets et leurs versions pour que chacun puisse recréer le même environnement.
Générer requirements.txt
# Exporter tous les paquets installés avec leurs versions exactes
pip freeze > requirements.txtLe résultat ressemble à ceci :
certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.1Installer depuis requirements.txt
# Créer un nouvel environnement et installer les dépendances
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtBonnes pratiques pour requirements.txt
# Épingler les versions exactes en production (builds reproductibles)
requests==2.31.0
flask==3.0.2
# Utiliser >= pour le développement de bibliothèques (autoriser les mises à jour compatibles)
requests>=2.28
# Séparer les dépendances de développement dans un second fichier
# requirements-dev.txt :
-r requirements.txt
pytest==8.0.0
black==24.2.0
mypy==1.8.0# Installer les dépendances de développement (inclut aussi les dépendances de production)
pip install -r requirements-dev.txtScénario concret : résolution d’un conflit de dépendances
Vous rejoignez une équipe qui travaille sur une application web. Vous clonez le dépôt, créez un environnement virtuel et exécutez pip install -r requirements.txt. L’opération échoue avec un conflit de versions :
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
Package A 2.0 requires LibX>=3.0, but you have LibX 2.5 which is incompatible.Comment le résoudre :
# Voir quel paquet nécessite la dépendance conflictuelle
pip install pipdeptree
pipdeptree --reverse --packages LibX
# Option 1 : Mettre à jour le paquet conflictuel
pip install --upgrade LibX
# Option 2 : Trouver des versions compatibles
pip install "PackageA>=2.0" "PackageB>=1.0" --dry-run
# Régénérer requirements.txt avec les versions résolues
pip freeze > requirements.txtComparaison des outils d’environnement Python
| Fonctionnalité | venv | virtualenv | conda | Poetry |
|---|---|---|---|---|
| Intégré à Python | Oui (3.3+) | Non (pip install) | Non (installeur séparé) | Non (pip install) |
| Vitesse | Modérée | Rapide | Lente | Modérée |
| Gestion de version Python | Non | Non | Oui | Non (utiliser pyenv) |
| Dépendances non-Python | Non | Non | Oui (libs C, R, etc.) | Non |
| Support de fichier de verrouillage | Non | Non | environment.yml | poetry.lock |
| Résolution des dépendances | pip (basique) | pip (basique) | solveur conda | Avancée |
| Espace disque par env | ~20 Mo | ~20 Mo | ~500 Mo+ | ~20 Mo |
| Idéal pour | Projets Python standard | Support Python 2 legacy | Data science, ML, multi-langage | Paquets Python modernes avec dépendances strictes |
Utilisez venv pour les projets Python standard — c’est l’outil officiel, il ne nécessite rien de plus et fonctionne partout où Python tourne. Utilisez conda lorsque vous avez besoin de dépendances non-Python (NumPy avec BLAS, CUDA, paquets R). Utilisez Poetry quand vous avez besoin d’une résolution de dépendances stricte et d’un workflow moderne pour publier des paquets.
Environnements Virtuels en CI/CD et Docker
Pipelines CI/CD (exemple GitHub Actions)
# .github/workflows/test.yml
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install dependencies
run: |
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
- name: Run tests
run: |
source .venv/bin/activate
pytestDocker (build multi-étape)
# Étape de construction
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt
# Étape de production
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY . .
CMD ["python", "app.py"]Utiliser un environnement virtuel à l’intérieur de Docker est discutable — le conteneur fournit déjà l’isolation. Cependant, les builds multi-étapes avec venv produisent des images plus légères car les outils de construction et le cache pip restent dans l’étape builder.
Pièges et cas particuliers
Incompatibilité de version Python : un environnement virtuel est lié à la version Python qui l’a créé. Si vous passez de Python 3.11 à 3.12, les environnements existants peuvent être cassés. Recréez-les après les mises à jour majeures de Python.
Fuites avec --system-site-packages : créer un environnement avec python3 -m venv --system-site-packages .venv donne accès aux paquets installés globalement. C’est utile pour les paquets difficiles à installer via pip (comme PyGObject fourni par le système), mais cela signifie que pip freeze inclut les paquets système, polluant votre requirements.txt. Utilisez pip freeze --local pour ne lister que les paquets propres à l’environnement.
Le cache pip remplit le disque : pip met en cache les paquets téléchargés dans ~/.cache/pip/. Sur les serveurs de build, ce cache grossit sans limite. Utilisez pip install --no-cache-dir ou exécutez périodiquement pip cache purge.
L’activation est spécifique au shell : si vous utilisez source .venv/bin/activate dans un script qui s’exécute dans un sous-shell, l’activation ne persiste pas. Appelez directement le binaire Python : .venv/bin/python script.py ou .venv/bin/pip install package.
Politique d’exécution PowerShell sous Windows : par défaut, PowerShell bloque l’exécution des scripts, y compris l’activation. Corrigez-le une fois par utilisateur :
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserEnvironnements virtuels sur lecteurs réseau : les environnements virtuels utilisent des liens symboliques vers l’interpréteur Python. Certains systèmes de fichiers réseau (SMB, NFS) ne supportent pas les liens symboliques, ce qui fait échouer l’environnement. Créez toujours les environnements sur le disque local.
Résolution de Problèmes
« No module named venv »
# Debian/Ubuntu — installer le module venv
sudo apt install python3-venv
# Certaines distributions livrent Python sans venv
# Vérifiez sa disponibilité :
python3 -m venv --help« pip install » échoue avec des erreurs de permissions
# Si vous voyez "Permission denied" — vous avez probablement oublié d'activer l'environnement
source .venv/bin/activate
pip install requests
# N'utilisez JAMAIS sudo pip install — cela modifie les paquets système
# Si vous avez besoin de paquets système, utilisez apt/dnf à la placeL’environnement utilise la mauvaise version de Python
# Spécifier la version Python lors de la création de l'environnement
python3.12 -m venv .venv
# Ou utiliser le chemin complet
/usr/bin/python3.12 -m venv .venv
# Vérifier la version à l'intérieur de l'environnement
source .venv/bin/activate
python --versionLes paquets s’installent en global plutôt que dans l’environnement
# Vérifier que pip appartient à l'environnement
which pip
# Devrait afficher : .venv/bin/pip
# S'il affiche /usr/bin/pip — l'environnement n'est pas activé
source .venv/bin/activateRésumé
python3 -m venv .venvcrée un environnement Python isolé — chaque projet dispose de ses propres paquets sans affecter les autres projets ni le Python système- Activez avec
source .venv/bin/activatepour que le Python et le pip de l’environnement deviennent les outils par défaut dans votre session shell actuelle pip freeze > requirements.txtcapture les versions exactes des dépendances — partagez ce fichier dans le contrôle de version pour que les autres puissent recréer un environnement identiquepip install -r requirements.txtdans un environnement vierge reproduit l’ensemble des dépendances — épinglez toujours les versions avec==pour les déploiements en production- N’utilisez jamais
sudo pip install— cela modifie les paquets système et crée des conflits. Les environnements virtuels éliminent entièrement le besoin d’accès root - Recréez les environnements après les mises à jour de Python — ils sont liés à la version Python qui les a créés et peuvent être cassés lors des changements de version majeure