Environnements virtuels Python : utiliser venv et uv

Un projet Python ne devrait pas installer ses dépendances directement dans l’environnement Python du système. Deux projets peuvent avoir besoin de versions différentes de Django, de Requests ou de n’importe quelle autre bibliothèque, et une mise à jour globale peut rapidement casser quelque chose ailleurs.

La solution consiste à créer un environnement virtuel propre à chaque projet. Aujourd’hui, Python fournit directement l’outil venv dans sa bibliothèque standard. Pour la majorité des projets, il suffit largement. Des outils plus récents comme uv peuvent ensuite simplifier encore la gestion de Python et des dépendances.

Pourquoi utiliser un environnement virtuel ?

Un environnement virtuel contient son propre interpréteur Python et son propre répertoire de paquets. Les bibliothèques installées dans un projet n’interfèrent donc pas avec celles du système ni avec celles d’un autre projet.

• Chaque projet peut utiliser ses propres versions de dépendances.
• Une mise à jour ne modifie pas les autres projets.
• On évite d’installer des paquets avec pip dans le Python géré par Debian ou Ubuntu.
• L’environnement peut être supprimé et recréé sans toucher au code du projet.

Ce dernier point est devenu particulièrement important sur les distributions Linux récentes. Elles peuvent marquer leur Python comme externally managed afin d’empêcher pip de modifier directement les paquets appartenant au système. Créer un environnement virtuel est la bonne solution ; utiliser --break-system-packages pour contourner cette protection ne devrait pas devenir une habitude.

Créer un environnement avec venv

Sur Debian ou Ubuntu, commencez par vérifier que le support de venv est installé :

sudo apt update
sudo apt install python3-venv

Placez-vous ensuite dans le répertoire de votre projet et créez un environnement nommé .venv :

mkdir mon-projet
cd mon-projet

python3 -m venv .venv

Le nom .venv n’est pas obligatoire, mais il est devenu une convention pratique. De nombreux éditeurs et outils de développement le détectent automatiquement.

Activer l’environnement

Sous Linux et macOS :

source .venv/bin/activate

Le nom de l’environnement apparaît généralement au début du prompt :

(.venv) etienne@serveur:~/mon-projet$

Vous pouvez vérifier quel interpréteur est utilisé :

which python
python --version
python -m pip --version

Le chemin retourné par which python doit maintenant pointer vers le répertoire .venv du projet.

Installer les dépendances

Une fois l’environnement activé, pip installe les paquets uniquement dans celui-ci :

python -m pip install --upgrade pip
python -m pip install django

J’utilise volontairement python -m pip plutôt que simplement pip. Cela garantit que l’on appelle le pip associé à l’interpréteur Python actuellement utilisé.

Pour connaître les paquets installés :

python -m pip list

Conserver la liste des dépendances

Sur un petit projet utilisant encore un fichier requirements.txt, vous pouvez enregistrer l’état de l’environnement :

python -m pip freeze > requirements.txt

Puis recréer les dépendances sur une autre machine :

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

Pour un projet moderne un peu plus structuré, pyproject.toml est généralement préférable pour déclarer les dépendances. L’environnement virtuel reste cependant le même principe : il contient les paquets installés, tandis que les fichiers du projet décrivent comment le reconstruire.

Ne pas versionner .venv

Le répertoire de l’environnement virtuel ne doit pas être ajouté à Git. Ajoutez simplement ceci dans .gitignore :

.venv/

Un environnement virtuel n’est pas destiné à être copié d’une machine à l’autre. Il vaut mieux le recréer à partir des dépendances déclarées par le projet.

Quitter ou supprimer l’environnement

Pour revenir au Python normal de votre session :

deactivate

Et si vous souhaitez repartir de zéro, il suffit de supprimer le répertoire puis de le recréer :

rm -rf .venv
python3 -m venv .venv

Et avec uv ?

venv a l’avantage d’être fourni avec Python et de ne nécessiter aucun outil supplémentaire. Pour beaucoup de projets, c’est exactement ce qu’il faut.

uv va plus loin : il peut créer les environnements, installer les dépendances, gérer plusieurs versions de Python et prendre en charge un projet à partir de son fichier pyproject.toml. Il est donc intéressant lorsque vous voulez réduire le nombre d’outils nécessaires autour d’un projet Python.

Une fois uv installé selon la documentation officielle, la création d’un environnement ressemble à ceci :

uv venv

Par défaut, uv crée lui aussi un répertoire .venv. On peut ensuite installer un paquet :

uv pip install django

Ou travailler directement avec le mode projet :

uv init
uv add django
uv run python -c "import django; print(django.get_version())"

Dans ce mode, uv maintient l’environnement du projet et son fichier de verrouillage. Il n’est même plus nécessaire d’activer systématiquement .venv pour lancer une commande : uv run utilise directement le bon environnement.

venv ou uv : lequel choisir ?

Je garderais une règle simple :

• venv si vous voulez la solution standard, minimale et disponible avec Python.
• uv si vous voulez également gérer les dépendances, les versions de Python et l’exécution du projet avec un seul outil.

Les deux solutions reposent sur la même idée : ne pas mélanger les dépendances de vos projets avec le Python du système.

Et VirtualEnvWrapper ?

VirtualEnvWrapper a longtemps été très pratique pour créer et retrouver des environnements centralisés avec des commandes comme mkvirtualenv ou workon. Pour un projet actuel, je ne l’installerais plus par défaut : un répertoire .venv placé directement dans chaque projet est plus simple à comprendre, mieux détecté par les outils modernes et ne nécessite aucune configuration supplémentaire du shell.

Il reste évidemment possible d’utiliser VirtualEnvWrapper sur un environnement existant si votre workflow en dépend. Mais pour démarrer un nouveau projet, venv ou uv constituent aujourd’hui des points de départ plus simples.

À retenir

• Créez un environnement virtuel par projet.
• Gardez-le dans .venv et excluez ce dossier de Git.
• N’installez pas les dépendances d’un projet dans le Python système.
• Utilisez python -m pip pour être certain d’installer dans le bon interpréteur.
• Choisissez venv pour la simplicité ou uv pour un workflow plus intégré.

Documentation : venv dans la documentation Python, guide PyPA sur pip et les environnements virtuels et environnements avec uv.