« error: externally-managed-environment » de pip et la PEP 668

Ce que c'est

error: externally-managed-environment est la réponse de pip (à partir de pip 23.0) lorsqu'il trouve un fichier marqueur EXTERNALLY-MANAGED dans le répertoire de la bibliothèque standard de l'installation Python cible ; le bloc qui suit commence par × This environment is externally managed. En dehors d'un environnement virtuel, il bloque aussi pip install --user. La PEP 668 définit ce marqueur : un distributeur (une distribution Linux, mais aussi conda ou un système similaire) le place pour indiquer que cette installation de Python est gérée par autre chose que pip ; pip ne doit donc pas y installer, mettre à jour ou supprimer directement des paquets. La page de spécification du Python Packaging User Guide documente le même marqueur ainsi que le comportement recommandé pour les installeurs. Le message vient de pip, pas de Python ; le fichier marqueur peut lui-même contenir le texte de correction proposé par le distributeur, qu'il vaut mieux lire avant d'appliquer une solution générique.

Pourquoi c'est important

Avant la PEP 668, un pip install exécuté hors d'un environnement virtuel pouvait écraser ou masquer sans bruit un paquet que le gestionnaire de paquets du système gère aussi et dont il dépend, ce qui cassait des outils système conçus pour une version précise. Le marqueur remplace cette corruption silencieuse par un échec explicite, au prix de scripts et d'images de conteneur qui supposaient des installations globales sans restriction et qui ne fonctionnent plus.

Comment l'appliquer

• Diagnostic : trouvez le marqueur avec python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))" et cherchez EXTERNALLY-MANAGED dans ce répertoire ; son contenu indique souvent la solution préférée de la distribution.
• Solutions, de la moins invasive à la plus invasive :
  1. Utiliser un environnement virtuel pour le projet : python3 -m venv .venv && source .venv/bin/activate && pip install ... — cela isole totalement les installations de l'interpréteur géré, et c'est la solution vers laquelle la PEP 668 cherche à orienter.
  2. Installer un outil en ligne de commande autonome avec pipx install <tool>, qui crée un environnement isolé propre à chaque outil.
  3. Installer la version empaquetée par la distribution avec son gestionnaire de paquets (par ex. apt install python3-<name>) lorsqu'elle existe.
  4. Uniquement dans un environnement jetable, dédié à une seule tâche (une image de conteneur temporaire, une étape de CI dont l'interpréteur n'est jamais réutilisé ensuite), forcer l'installation avec pip install --break-system-packages ... (pip 23.0.1+, ou PIP_BREAK_SYSTEM_PACKAGES=1) — un dernier recours risqué, qui peut écraser des fichiers appartenant au gestionnaire de paquets du système, et non un indicateur à ajouter partout par défaut.
• Dangereux ou trompeur : supprimer le fichier EXTERNALLY-MANAGED. Cela fait taire l'avertissement sans rien isoler, et une mise à niveau de la distribution peut simplement le remettre en place.

Pièges

• Ajouter --break-system-packages sur un hôte partagé ou de longue durée « pour faire disparaître l'erreur » transforme chaque installation future précisément en ce conflit que le marqueur est censé empêcher.
• Considérer le marqueur comme un bug de pip ; il s'agit d'une politique délibérée de la distribution, que pip respecte.