Demander un paquet en installe plusieurs. Chez Salomé Kader, qui tient une boutique de bougies en ligne à Grenoble, installer requests dans un environnement neuf, pour appeler l'API d'un transporteur, a affiché Successfully installed certifi-2026.8.10 charset_normalizer-3.5.2 idna-3.20 requests-2.35.0 urllib3-2.7.1, cinq paquets pour un seul nom demandé. Quatre d'entre eux sont des décisions prises par d'autres personnes, ils seront mis à jour selon leur propre calendrier, et il revient désormais à Salomé de les garder fonctionnels.
Ils se sont installés dans le dossier et nulle part ailleurs. Depuis l'interpréteur de l'environnement, l'import réussit ; depuis l'interpréteur du système dans le même terminal, import requests répond ModuleNotFoundError: No module named 'requests'. C'est tout le mécanisme, et c'est pour ça que la même commande fonctionne chez une collègue et pas chez vous.
Ce qu'un environnement virtuel change, exactement
C'est un dossier avec son propre interpréteur et son propre site-packages, et une valeur qui trahit lequel on utilise : à l'intérieur, sys.prefix diffère de sys.base_prefix. Cette seule ligne est le moyen fiable de savoir dans quel environnement on se trouve, et elle vaut plus qu'un coup d'œil à l'invite, parce que l'invite peut être trompeuse alors que cette comparaison ne l'est pas.
Quatre couches, un seul import
Ce qu'un import cherche, et la couche que le dossier remplace
Un environnement virtuel permute les couches médianes de résolution pour isoler les paquets du projet.
- Code source du projetRecherché en premier, d'où le risque de conflit si un fichier local partage le nom d'un moduleprioritaire
- Répertoire site-packages de l'environnementContient les dépendances du projet sans interférer avec les bibliothèques systèmeisolé
- Interpréteur virtuel de l'environnementsys.prefix pointe vers ce dossier spécifique tandis que sys.base_prefix reste sur le systèmeciblé
- Interpréteur global du systèmeDemeure présent sur l'hôte mais se trouve écarté du chemin de recherche du projetmasqué
Activer un environnement ajuste uniquement PATH. Appeler l'interpréteur par son chemin complet garantit le même isolement sans étape préalable.
Un environnement neuf ne contient que pip. Tout ce que la machine avait installé globalement lui est invisible, volontairement, et c'est exactement cette propriété qu'on achète : deux projets qui veulent des versions différentes d'une même bibliothèque cessent d'être un problème à résoudre.
Activer est un confort, le chemin est le fait
Activer modifie votre PATH pour que python désigne l'interpréteur de l'environnement. Rien d'autre ne se passe, ce qui explique que tous les problèmes de cette zone se règlent de la même façon : arrêter de dépendre de l'activation et appeler l'interpréteur par son chemin. ./boutique-env/bin/python -m pip install requests fonctionne qu'un environnement soit activé ou non, dans une tâche planifiée, dans un script de déploiement, ou dans un éditeur qui a lancé son propre terminal.
Invocation de l'interpréteur
La décision entre activation de session et chemin explicite
Dépendre de l'état d'un terminal expose aux incohérences d'environnement dans les outils d'automatisation.
- Activation interactive dans le shellModification temporaire du PATHPratique pour travailler dans son terminal mais inopérant dans les planificateurs ou sous-shells.
- Nécessite source bin/activate
- Fragile lors des appels automatisés
- Appel direct par le chemin completExécution par ./env/bin/pythonDésigne sans ambiguïté l'interpréteur voulu sans dépendre d'aucune variable de session.
- Fonctionne dans cron et les scripts CI
- Empêche pip de viser le mauvais Python
Employer python -m pip via le chemin direct de l'environnement interdit toute divergence entre l'outil d'installation et l'interpréteur cible.
Deux habitudes en découlent. Lancer pip comme python -m pip plutôt que comme pip, pour que le pip exécuté et l'interpréteur ciblé ne puissent jamais diverger. Et ne jamais installer dans l'interpréteur du système : sur une machine à jour, il refusera le plus souvent, et là où il ne refuse pas, cela place les dépendances d'un projet où tous les autres projets peuvent les voir.
Ce qui rend l'exécution reproductible
python -m pip freeze affiche exactement ce qui est installé, avec les versions exactes, cinq lignes pour l'installation ci-dessus, en commençant par certifi==2026.8.10. Le commiter est le minimum : sans ça, la personne suivante récupère ce qui était disponible le jour où elle a lancé l'installation, et le rapport de bug commence par deux jeux de versions différents.
Arborescence d'empaquetage
La dépendance visible et ses paquets sous-jacents
Un seul import en apparence modeste installe une cascade de bibliothèques tierces qu'il convient de figer.
- Paquet direct demandérequests déclaré explicitement par l'équipe dans pyproject.toml
- Dépendances transitives installéescertifi==2026.8.10, charset_normalizer, idna et urllib3 requis en coulisses
- Fichier de verrouillageEnregistre chaque numéro de version pour garantir des déploiements strictement reproductibles
- Maintenance de long termeChaque brique sous-jacente suit son propre cycle de publication et de correctifs de sécurité
La déclaration sépare les intentions directes des paquets induits, permettant à l'outil de verrouillage de figer l'ensemble sans confusion.
La forme actuelle vaut mieux qu'une liste figée, parce qu'une liste figée ne distingue pas les dépendances demandées directement des quatre qui sont arrivées avec elles. Déclarer requests dans pyproject.toml et laisser un outil écrire le fichier de verrouillage garde cette distinction, donc mettre à jour une chose ne demande pas de savoir lequel des cinq noms était réellement voulu.
Ce qu'on installe en 2026
uv est l'outil vers lequel la plupart des projets Python ont basculé d'ici 2026, gratuit et open source. Il crée l'environnement, résout et installe, et écrit un fichier de verrouillage, dans un seul programme là où il y en avait trois, et il est assez rapide pour que recréer l'environnement ne soit plus une chose qu'on évite. Il a remplacé la combinaison venv plus pip plus pip-tools, et la note honnête est que python -m venv et python -m pip sont toujours présents, ce qui est la raison pour laquelle cette page est écrite avec eux.
Transition des outils
Le pont vers uv et pyproject.toml en 2026
L'écosystème Python a convergé vers un outil unique et un format standardisé pour simplifier la gestion des dépendances.
- 01Création d'environnementuv venv remplace python -m venv avec une création quasi instantanée
- 02Déclaration des dépendancespyproject.toml formalise les paquets directs sous une syntaxe unique
- 03Résolution et verrouillageuv lock calcule le graphe complet sans empiler d'utilitaires externes
- 04Installation synchroniséeuv sync ajuste le dossier local pour correspondre fidèlement au verrou
uv unifie les étapes de création, de résolution et d'installation au sein d'un binaire unique sans modifier la structure des dossiers virtuels.
pyproject.toml est le fichier, gratuit avec l'écosystème et la norme en 2026. Il a remplacé setup.py et la convention informelle du requirements.txt, et le gain pratique est que les dépendances déclarées et celles réellement résolues sont deux listes distinctes dans deux fichiers distincts, ce qui est la distinction dont le paragraphe précédent a besoin.
Le blocage : ne pas savoir quel interpréteur répond
C'est le blocage de tout le pilier, et il arrive tôt : quelqu'un qui sait écrire du Python rencontre un environnement qui refuse de s'installer, en conclut qu'elle n'est pas douée pour la programmation, et rencontre en réalité l'empaquetage, dont personne ne lui a dit qu'il s'agissait d'un sujet à part. C'en est un, il a son propre vocabulaire, et il prend une quinzaine plutôt qu'un après-midi.
Diagnostic d'environnement
La procédure pour identifier l'interpréteur qui répond
Face à une bibliothèque introuvable malgré son installation, une vérification ordonnée rétablit la cohérence.
- 01Interroger sys.executableLancer python -c "import sys; print(sys.executable)" pour repérer le binaire actif
- 02Comparer prefix et base_prefixS'assurer que sys.prefix diffère de sys.base_prefix pour confirmer l'environnement virtuel
- 03Contrôler la cible de pipExécuter python -m pip --version pour vérifier la concordance entre pip et l'interpréteur
- 04Vérifier le dossier site-packagesInspecter les dossiers installés pour détecter d'éventuels conflits de noms locaux
Connaître le chemin exact retourné par sys.executable résout la quasi-totalité des anomalies d'importation au sein d'un projet.
L'habitude qui règle l'essentiel : avant que quoi que ce soit d'autre n'échoue, lancer python -c "import sys; print(sys.executable)" et lire à quel interpréteur on parle réellement. Presque toute installation qui ne marche pas vient de ce chemin, différent de celui qui exécute le code. Ce que cet interpréteur trouve une fois les paquets présents est décrit dans la bibliothèque standard, ce qui se passe entre le code et le processeur reste posé par l'exécution du code, et livrer l'environnement lui-même plutôt que de le reconstruire relève de les conteneurs.