Cours de Python / Créer un environnement virtuel et gérer les paquets avec pip

Un environnement virtuel sépare les paquets Python d’un projet de ceux des autres projets. Utilisez python -m pip pour installer les paquets avec le Python choisi, puis conservez leurs versions dans un fichier de dépendances afin de pouvoir recréer l’environnement.

Comprendre ce que l’environnement sépare

Deux projets peuvent demander des versions différentes d’une même bibliothèque. Si vous modifiez une installation commune pour satisfaire le premier, le second peut cesser de fonctionner. Un dossier .venv par projet réduit ce conflit en séparant les installations de paquets.

Cette séparation concerne les paquets, pas les droits d’accès aux fichiers. Un programme lancé dans un environnement virtuel conserve les droits de votre utilisateur : venv ne remplace donc pas une isolation de sécurité. Il utilise également la version de Python avec laquelle vous l’avez créé ; il ne télécharge pas automatiquement un autre interpréteur.

La documentation officielle de venv précise le fonctionnement de cette séparation. Si vous utilisez VS Code pour exécuter vos scripts, sélectionnez aussi cet environnement dans l’éditeur.

Créer l’environnement et l’utiliser

Dans le dossier d’un nouveau projet, exécutez la commande suivante avec l’interpréteur prévu. Sous macOS ou Ubuntu, utilisez python3 à la place de python si c’est le nom de votre installation. Si .venv existe déjà, vérifiez son rôle avant de le recréer.

python -m venv .venv

Pour l’activer dans Windows PowerShell :

.\.venv\Scripts\Activate.ps1

Dans un shell compatible avec cette commande, comme Bash ou Zsh sur macOS ou Ubuntu :

source .venv/bin/activate

L’activation change la recherche de la commande python dans le terminal courant. Elle ne modifie pas automatiquement les autres terminaux. Si PowerShell bloque le script d’activation, utilisez directement .\.venv\Scripts\python.exe à la place de python dans les commandes suivantes. Sous macOS et Ubuntu, l’équivalent est .venv/bin/python. Vous pouvez ainsi utiliser l’environnement sans assouplir la politique d’exécution de la machine.

Avant toute installation, contrôlez l’interpréteur et pip :

python -c "import sys; print(sys.executable)"
python -m pip --version

Les deux chemins doivent appartenir au même dossier .venv. Une commande pip lancée seule peut être associée à un autre Python ; la forme python -m pip rend ce lien explicite.

Installer et enregistrer les dépendances

L’exemple utilise pandas, une bibliothèque pour les données tabulaires. Après avoir activé l’environnement et vérifié les chemins, lancez les commandes dans l’ordre. La première installation demande une connexion au dépôt de paquets ; installez uniquement les bibliothèques utiles au projet et vérifiez leur nom ainsi que leur provenance.

python -m pip install pandas
python -m pip show pandas
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

show affiche notamment le nom, la version et l’emplacement de pandas. L’emplacement doit correspondre à votre environnement. freeze enregistre les paquets installés dans requirements.txt ; pandas et ses dépendances peuvent donc produire plusieurs lignes. La dernière commande lit ce fichier. Dans le même environnement, elle peut simplement indiquer que les exigences sont déjà satisfaites ; dans un nouvel environnement compatible, elle permet de réinstaller ces versions.

Le nom utilisé pour installer un paquet et celui utilisé après import ne sont pas toujours identiques. Ici, les deux sont pandas. Vous pouvez vérifier l’import avec python -c "import pandas; print(pandas.__version__)" et comparer la version à celle indiquée par pip show pandas.

Un fichier produit par freeze décrit l’état installé : ce n’est pas une garantie de reproduction sur tous les systèmes, ni une vérification des empreintes des fichiers téléchargés. Les dépendances et les distributions disponibles peuvent varier selon Python et le système. La référence de pip freeze explique les éléments inclus ou omis par défaut.

Conservez le fichier de dépendances à côté de vos scripts, hors de .venv. Certaines versions de PowerShell utilisent un encodage différent lors d’une redirection avec >. Si la lecture de requirements.txt échoue, examinez son contenu et son encodage, puis enregistrez-le en UTF-8 avant de retenter l’installation.

Diagnostiquer une erreur avant de réinstaller

Commencez par ces trois contrôles dans le terminal qui exécute le programme :

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip check

Si les dépendances déclarées sont compatibles, pip check doit afficher No broken requirements found.. Ce résultat ne teste pas tout le fonctionnement de votre application : il contrôle les relations de dépendance déclarées par les paquets installés.

• ModuleNotFoundError : identifiez le Python qui exécute réellement le script, puis installez le paquet dans cet environnement. Une installation globale en administrateur ne corrige pas un mauvais choix d’interpréteur.
• Version incompatible ou paquet absent : lisez le message de pip et vérifiez les versions de Python prises en charge par le paquet. Évitez de modifier plusieurs dépendances au hasard.
• Erreur de certificat ou de proxy : vérifiez la configuration du réseau et la chaîne de confiance. Désactiver la vérification TLS ne résout pas leur cause.

Pour quitter un environnement activé, saisissez deactivate. Pour retirer pandas de cet environnement, utilisez python -m pip uninstall pandas après avoir vérifié le chemin de Python ; pip demande normalement confirmation. Consultez le guide officiel de pip pour les commandes de gestion. Avant de reconstruire .venv, vérifiez que vos scripts et votre fichier de dépendances se trouvent bien à l’extérieur.