Python : créer et utiliser un environnement virtuel pour chaque projet

Un environnement virtuel est un répertoire associé à une installation de Python et qui possède son propre ensemble de paquets. Le module standard venv permet d’en créer un et, par défaut, isole ses paquets de ceux installés dans l’installation de base. Chaque projet peut ainsi avoir des dépendances indépendantes, au lieu de devoir partager une seule collection de paquets sur tout l’ordinateur. Documentation officielle de venv

Imaginez deux projets : l’un exige une version précise d’une bibliothèque et l’autre dépend d’une version différente. Installer les deux versions dans un même environnement global peut entraîner des incompatibilités. Avec un environnement distinct pour chaque projet, chacun peut installer ses paquets sans modifier l’ensemble de l’autre projet. Le principal avantage est l’isolation des dépendances, et non une séparation complète du système ni la garantie que le projet fonctionnera à l’identique sur tous les ordinateurs.

venv fait partie de la bibliothèque standard de Python depuis la version 3.3. L’environnement repose sur une installation Python existante, appelée Python de base, et utilise la version de l’interpréteur avec laquelle il a été créé. Créer un environnement n’installe donc pas à lui seul n’importe quelle version de Python dont le projet pourrait avoir besoin : il faut d’abord disposer de l’interpréteur approprié. Documentation officielle de venv

Avant de créer l’environnement, ouvrez un terminal et vérifiez que Python est disponible. Le nom des commandes peut varier selon le système et le mode d’installation. Sous macOS et dans de nombreuses distributions Linux, essayez python3 --version ; sous Windows, py --version ou python --version. Si une commande n’est pas reconnue, essayez les autres options disponibles et vérifiez quel interpréteur chacune invoque. Ce guide ne suppose pas que toutes les machines utilisent une commande identique.

Créez ou ouvrez le dossier du projet et exécutez les commandes depuis celui-ci. .venv est un nom courant pour le répertoire de l’environnement : le point initial fait que certains explorateurs de fichiers l’affichent comme caché, mais ne modifie pas le fonctionnement de Python. Le guide Python Packaging User Guide recommande également de travailler dans un environnement virtuel lors de l’installation de paquets pour un projet. Python Packaging User Guide

Vérifiez aussi que vous avez le droit d’écrire dans le dossier et que l’interpréteur sélectionné est bien celui que vous souhaitez utiliser. Si plusieurs installations sont présentes, le résultat de --version aide à repérer un choix inattendu. L’environnement hérite de la version de Python utilisée pour le créer : mieux vaut donc faire ce choix avant d’installer des paquets.

L’emplacement depuis lequel vous lancez la commande compte, car .venv sera créé dans le dossier courant. Le conserver dans le projet permet d’identifier plus facilement à quel projet il correspond. Si un répertoire .venv existe déjà, vérifiez son contenu et son rôle avant d’essayer d’en créer un autre au même emplacement. Choisissez l’interpréteur en connaissance de cause : sur une machine comportant plusieurs versions de Python, le nom de la commande ne suffit pas à indiquer quelle installation sera utilisée.

Le module s’exécute comme un module Python : -m venv demande à l’interpréteur d’invoquer venv, et .venv désigne le répertoire à créer. Utilisez la commande correspondant à votre installation :

• Windows : py -m venv .venv (si le lanceur py n’est pas disponible, essayez python -m venv .venv).
• macOS ou Linux : python3 -m venv .venv (si python3 n’existe pas, vérifiez si python pointe vers l’interpréteur souhaité).

La documentation indique que la création génère le répertoire de destination et des fichiers de configuration. Dans l’environnement, les exécutables sont organisés différemment selon la plateforme : sous Windows, ils se trouvent dans Scripts ; sur les systèmes de type Unix, comme macOS et Linux, dans bin. Documentation officielle de venv La création n’affiche généralement pas de confirmation détaillée ; vous pouvez vérifier le résultat en recherchant .venv dans le dossier du projet. En cas d’échec, lisez le message complet avant de réessayer : il peut signaler un interpréteur absent, un dossier non accessible en écriture ou un environnement incomplet. Ne supposez pas que relancer la même commande réglera le problème. Si la destination existe déjà, examinez-la avant de décider quoi faire, au lieu de supprimer des fichiers sans connaître leur rôle. La structure de la commande reste similaire d’une plateforme à l’autre, mais la commande de l’interpréteur et l’organisation des répertoires obtenus peuvent varier. Garder le répertoire de l’environnement dans le projet facilite aussi l’utilisation ultérieure des commandes d’activation. Une fois créé, l’environnement peut être activé à l’aide du script correspondant à votre terminal. Sa création n’installe pas à elle seule les paquets du projet : cette étape intervient après l’activation. Il est utile de distinguer clairement la création de l’environnement, l’installation des paquets et l’exécution du projet. Si vous ne savez pas quel interpréteur a été invoqué, revenez à la vérification de la version de Python et identifiez l’installation avant de poursuivre. Vous éviterez ainsi de créer l’environnement du projet avec une version inattendue. Aucun texte de confirmation particulier n’est nécessaire pour que la création ait réussi : la présence du répertoire et des fichiers d’environnement constitue la vérification pratique. En revanche, un message d’échec doit être compris avant de continuer. En vérifiant le dossier et en lisant le message, vous pouvez distinguer un problème de création d’un problème ultérieur d’activation ou d’installation de paquets. Le nom .venv est conventionnel et non obligatoire ; dans ces exemples, il s’agit du nom choisi pour la destination. Utilisez donc ce même nom dans les commandes suivantes. Si vous en choisissez un autre, les chemins d’activation devront correspondre à ce nom. Les exemples ci-dessous partent du principe que vous avez conservé .venv. Cela rend les commandes cohérentes, de la création à l’activation, puis à la désactivation. L’environnement reste lié à l’installation Python utilisée pour le créer, ce qui explique pourquoi il est important de sélectionner l’interpréteur à l’avance. La commande crée un environnement local dans le dossier courant du projet ; elle ne copie pas tout le système d’exploitation et ne remplace pas l’installation Python de base. Cette limite est importante pour comprendre ce que signifie ici le terme « isolé ». L’étape suivante consiste à activer l’environnement dans le terminal de travail. Si vous ouvrez un autre terminal plus tard, il faudra peut-être l’y activer de nouveau. C’est normal et cela ne signifie pas que l’environnement a été supprimé. Les fichiers restent dans .venv tant que vous ne les supprimez pas.**

venv fournit ainsi un espace de travail local pour les paquets de chaque projet, créé avec l’interpréteur Python sélectionné. Le dossier d’exécutables propre à chaque plateforme explique pourquoi les chemins d’activation diffèrent, même si la méthode de création est comparable. Après avoir vérifié que le répertoire existe, passez à la commande adaptée à votre terminal.

Une fois l’environnement créé, activez-le avec le script adapté au shell utilisé. Sous macOS et Linux, depuis le dossier du projet, exécutez source .venv/bin/activate. Sous Windows, la commande dépend du terminal : dans PowerShell, utilisez .venv\Scripts\Activate.ps1 ; dans l’invite de commandes, .venv\Scripts\activate.bat. N’ajoutez pas d’espace au début lorsque vous copiez l’une ou l’autre commande.

Une fois l’environnement activé, le terminal affiche généralement (.venv) au début de l’invite. C’est un indice pratique, mais pas la seule vérification possible. Vous pouvez alors installer une bibliothèque, par exemple avec python -m pip install nom-du-paquet. Passer par le python actif pour invoquer pip aide à associer l’installation à l’interpréteur sélectionné. La documentation sur l’empaquetage décrit l’installation avec pip dans un environnement virtuel. Python Packaging User Guide

Exécutez le programme avec python fichier.py, en remplaçant fichier.py par le nom réel du fichier. Pour confirmer l’interpréteur utilisé, python --version indique sa version ; vous pouvez aussi consulter son chemin avec python -c "import sys; print(sys.executable)". Installez et exécutez avec le même environnement actif : vous réduisez ainsi le risque d’installer un paquet dans une installation et d’exécuter le projet avec une autre.

La commande d’activation propre au shell modifie la session du terminal courant afin que les commandes comme python utilisent l’interpréteur de l’environnement. C’est pourquoi il est important d’activer l’environnement dans le terminal où vous comptez installer des paquets et exécuter le projet. Si vous ouvrez un autre terminal, ne partez pas du principe qu’il utilise déjà le même environnement : activez-le également dans cette fenêtre, puis vérifiez l’invite ou le chemin de l’interpréteur. Cette vérification peut aider à comprendre pourquoi un paquet semble introuvable alors qu’une commande d’installation a semblé réussir. Utilisez le vrai nom du fichier lors de l’exécution et restez dans le dossier du projet, sauf si celui-ci exige un autre répertoire de travail. Ces exemples sont des commandes à saisir dans le terminal, et non du texte à ajouter au fichier Python.

Pour quitter l’environnement actif, saisissez deactivate et appuyez sur Entrée. Cette commande cesse d’utiliser l’environnement virtuel dans ce terminal ; elle ne supprime pas les fichiers de .venv et ne désinstalle pas ses paquets. Pour reprendre le travail sur le projet, ouvrez un terminal dans son dossier et répétez la commande d’activation correspondant à Windows, macOS ou Linux. Documentation officielle de venv

Si l’activation échoue dans PowerShell avec un message concernant l’exécution de scripts, ne modifiez pas à l’aveugle les paramètres de sécurité de l’ordinateur. Vous pouvez utiliser un autre terminal compatible, comme l’invite de commandes, et consulter la documentation Python pour Windows afin de résoudre la configuration propre à votre installation. Microsoft Learn : Python sous Windows Si le message indique « commande introuvable », vérifiez d’abord que vous êtes dans le dossier du projet, que .venv existe et que vous avez saisi le chemin adapté à votre plateforme.

Si pip indique qu’un paquet est déjà installé mais que le programme ne le trouve pas, vérifiez sys.executable et le chemin d’installation : le terminal n’utilise peut-être pas l’environnement attendu. Si la création échoue parce que venv est indisponible, vérifiez l’installation et les composants Python de votre système ; les détails dépendent du mode d’installation de Python. Ne supprimez pas une installation globale comme première mesure.

Pour diagnostiquer un problème, examinez les étapes séparément au lieu de modifier plusieurs paramètres à la fois. Vérifiez d’abord le dossier et le répertoire d’environnement, puis le chemin de l’interpréteur, et enfin relancez la commande concernée. L’absence de (.venv) dans l’invite peut fournir un indice, mais sys.executable indique directement quel interpréteur la commande python actuelle invoque. La désactivation est réversible : elle change le contexte actif du terminal, pas les fichiers stockés dans le projet. Une fois l’étape défaillante identifiée, utilisez la commande d’activation correspondant au système et au shell, plutôt que de copier une commande destinée à un autre terminal.

Un environnement virtuel est un outil d’isolation local, pas un fichier de spécification du projet. Si une autre personne doit reconstruire l’ensemble des paquets, consignez les dépendances dans un fichier géré par le projet. Pour les projets simples utilisant pip, une méthode courante consiste à créer une liste avec python -m pip freeze > requirements.txt puis, dans un autre environnement, à l’installer avec python -m pip install -r requirements.txt. Cette liste reflète les paquets installés et leurs versions à cet instant ; vérifiez qu’elle convient au partage et à la maintenance avant de la considérer comme une description complète du projet.

N’incluez pas .venv dans le dépôt : il s’agit généralement d’un répertoire local, potentiellement volumineux et lié au système ainsi qu’à l’interpréteur d’origine. Incluez plutôt les fichiers qui décrivent le projet et ses dépendances, selon le processus utilisé par l’équipe. Lorsque vous clonez ou copiez le projet sur une autre machine, créez un nouvel environnement avec la version de Python appropriée et installez-y les dépendances enregistrées.

L’isolation de venv a des limites délibérées. Ce n’est ni une machine virtuelle ni un conteneur : elle ne remplace pas l’installation de l’interpréteur, ne copie pas nécessairement tout le système d’exploitation et n’élimine pas les différences entre plateformes. De plus, puisque l’installation de base reste en dehors de l’environnement, un environnement virtuel ne remplace pas les pratiques de sécurité, de mise à jour et de gestion des versions. Au quotidien, le cycle est simple : se placer dans le projet, créer .venv, l’activer, installer les dépendances, exécuter le programme et le désactiver une fois le travail terminé.

L’environnement lui-même n’est pas le document dont une autre personne a besoin pour reproduire l’ensemble des paquets du projet. Un fichier de dépendances fournit ce relevé sous une forme utilisable lors de la création d’un environnement neuf. La commande freeze liste les paquets installés et leurs versions au moment de son exécution ; il faut donc examiner et entretenir son résultat, plutôt que de supposer qu’il décrit tous les aspects d’un projet. De même, exclure .venv du dépôt évite de confondre un répertoire local avec la description partagée du projet. Pour recréer l’environnement sur une autre machine, choisissez une installation Python adaptée et installez-y les dépendances. On distingue ainsi les fichiers du projet, les informations sur ses dépendances et l’environnement local utilisé pour l’exécuter. Cette démarche rappelle la limite essentielle : isoler les paquets est utile, mais ne rend pas identiques des ordinateurs ou des systèmes d’exploitation différents.