Pips Fehlermeldung „error: externally-managed-environment“ und PEP 668

Worum es geht

error: externally-managed-environment ist die Antwort von pip (ab pip 23.0), wenn im Standardbibliotheksverzeichnis der Ziel-Python-Installation eine Markierungsdatei EXTERNALLY-MANAGED liegt; der darunter folgende Block beginnt mit × This environment is externally managed. Ausserhalb einer virtuellen Umgebung blockiert pip damit auch pip install --user. PEP 668 definiert diese Markierung: Ein Distributor (eine Linux-Distribution, aber auch conda oder ein ähnliches System) legt sie an, um zu erklären, dass diese Python-Installation von etwas anderem als pip verwaltet wird. Pip darf daher keine Pakete direkt in sie installieren, aktualisieren oder daraus entfernen. Die Spezifikationsseite des Python Packaging User Guide dokumentiert dieselbe Markierung und das empfohlene Verhalten von Installern. Die Meldung stammt von pip, nicht von Python; die Markierungsdatei selbst kann einen eigenen Lösungshinweis des Distributors enthalten, den man lesen sollte, bevor man eine generische Lösung anwendet.

Warum es wichtig ist

Vor PEP 668 konnte ein pip install ausserhalb einer virtuellen Umgebung ein Paket stillschweigend überschreiben oder verdecken, das auch der Paketmanager des Betriebssystems verwaltet und von dem er abhängt. Systemwerkzeuge, die gegen eine bestimmte Version gebaut waren, funktionierten dann nicht mehr. Die Markierung macht daraus einen lauten Fehler statt einer unbemerkten Beschädigung. Der Preis: Skripte und Container-Images, die uneingeschränkte globale Installationen voraussetzten, funktionieren nicht mehr.

So wird es angewendet

• Diagnose: Die Markierung mit python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))" lokalisieren und in diesem Verzeichnis nach EXTERNALLY-MANAGED suchen; der Inhalt nennt oft die bevorzugte Lösung der Distribution.
• Lösungen, vom geringsten zum stärksten Eingriff:
  1. Für das Projekt eine virtuelle Umgebung verwenden: python3 -m venv .venv && source .venv/bin/activate && pip install ... — Installationen sind damit vollständig vom verwalteten Interpreter getrennt; auf diese Lösung zielt PEP 668 ab.
  2. Ein eigenständiges CLI-Tool mit pipx install <tool> installieren; pipx legt für jedes Tool eine eigene isolierte Umgebung an.
  3. Die von der Distribution paketierte Version über deren Paketmanager installieren (z. B. apt install python3-<name>), sofern es sie gibt.
  4. Nur in einer Wegwerfumgebung für genau einen Zweck (ein temporäres Container-Image, ein CI-Schritt, dessen Interpreter danach nie wiederverwendet wird) mit pip install --break-system-packages ... (ab pip 23.0.1, oder PIP_BREAK_SYSTEM_PACKAGES=1) übersteuern — ein unsicherer letzter Ausweg, der Dateien überschreiben kann, die dem Paketmanager des Betriebssystems gehören, und kein Standard-Flag, das überall angehängt werden sollte.
• Unsicher bzw. irreführend: die Datei EXTERNALLY-MANAGED löschen. Das unterdrückt die Meldung, ohne irgendetwas zu isolieren, und ein Distributions-Upgrade kann die Datei einfach wieder anlegen.

Stolpersteine

• --break-system-packages auf einem gemeinsam genutzten oder langlebigen Host hinzuzufügen, „damit der Fehler verschwindet“, macht jede künftige Installation zu genau dem Konflikt, den die Markierung verhindern soll.
• Die Markierung für einen pip-Fehler halten; sie ist eine bewusste Richtlinie der Distribution, die pip lediglich befolgt.