externally-managed-environment in pip: Fehler beheben

Sie richten einen neuen Server mit Ubuntu 24.04, einen Raspberry Pi oder einen Mac mit Homebrew ein, tippen wie seit Jahren pip install requests, und pip bricht mit error: externally-managed-environment ab. Auf Ihrem alten Rechner funktioniert derselbe Befehl noch, und die Meldung bittet Sie, stattdessen apt, eine virtuelle Umgebung oder pipx zu verwenden.

Dieser Leitfaden erklärt, wovor der Fehler schützt, welche Systeme ihn einschalten und welche Lösungen wir in welcher Reihenfolge empfehlen, den Schalter zum Übergehen ganz am Schluss. Jeden Befehl haben wir an einer Nachstellung des Fehlers ausprobiert. Die letzten Abschnitte behandeln pip hinter einem Proxy-Server und eine erste Anfrage über einen Proxy aus der neuen Umgebung.

Was bedeutet „error: externally-managed-environment“?#

Es bedeutet, dass pip eine Markierung gefunden hat, laut der ein anderes Werkzeug diese Python-Installation verwaltet. PEP 668 legt die Markierung fest: eine Datei namens EXTERNALLY-MANAGED im Verzeichnis der Standardbibliothek des Interpreters, unter Debian 13 etwa /usr/lib/python3.13/. pip liest die Datei seit Version 23.0, erschienen im Januar 2023. Ist die Datei vorhanden und läuft pip nicht in einer virtuellen Umgebung, gibt pip den Text der Datei aus und beendet sich, ohne etwas zu installieren.

Wir haben den Fehler unter Windows 11 mit pip 26.2.1 nachgestellt: Den Markierungstext von Debian 13 haben wir in das Verzeichnis der Standardbibliothek eines Wegwerf-Pythons 3.14.8 gelegt und python -m pip install requests ausgeführt. Die Ausgabe entspricht dem, was Debian-Nutzer sehen:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.13/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Die ersten beiden Zeilen sowie note und hint stammen von pip. Der eingerückte Block ist der Text der Markierungsdatei und ändert sich deshalb mit dem System: Arch Linux schlägt pacman -S python-xyz vor, Homebrew brew install xyz, und beide verweisen zusätzlich auf eine virtuelle Umgebung und pipx.

Warum verweigert pip hier die Installation?#

Sonst würden zwei Paketmanager in dasselbe Verzeichnis schreiben, ohne voneinander zu wissen. Unter Debian, Ubuntu oder Arch sind Teile des Betriebssystems in Python geschrieben und importieren Bibliotheken, die der Paketmanager des Systems installiert hat. Dieser Paketmanager hält fest, welche Versionen diese Programme brauchen; pip liest diese Aufzeichnungen nicht. PEP 668 beschreibt die Folge: Ein pip install kann eine mit dem Betriebssystem ausgelieferte Bibliothek aktualisieren oder entfernen und sogar den Paketmanager von Fedora selbst, dnf, beschädigen.

Auch ein eigenes Verzeichnis für pip löst das nicht. Distributionen legen lokal installierte Pakete an Orten wie /usr/local ab, und in dem Aufbau, den PEP 668 empfiehlt, haben lokale Installationen Vorrang vor den Paketen der Distribution; die Python-Programme des Systems importieren also, was pip dort abgelegt hat. Die Markierung schafft Klarheit: Projekte bekommen eigene Umgebungen, und das System-Python bleibt so, wie die Distribution es gebaut hat.

Wie entscheidet pip, ob es eine Installation blockiert?#

1. Es prüft, ob es in einer virtuellen Umgebung läuft. In einer venv unterscheidet sich sys.prefix von sys.base_prefix, die Prüfung endet, und die Installation läuft.
2. Es sucht die Markierung in dem Verzeichnis, das sysconfig.get_path("stdlib") zurückgibt.
3. Es liest die Meldung aus dem Schlüssel Error der Datei oder, falls die Datei einen hat, aus einem übersetzten Schlüssel Error-<Sprache> und gibt sie aus.
4. Es blockiert sowohl pip install als auch pip uninstall. --user hilft nicht: pip install --user requests brach in unserem Test mit demselben Fehler ab. Auch sudo vor pip ändert nichts.
5. Die Option --break-system-packages überspringt die Prüfung, ebenso ihre Formen als Umgebungsvariable und in der Konfigurationsdatei, die weiter unten folgen.

Um zu sehen, welcher Fall bei Ihnen vorliegt, fragen Sie den Interpreter, den Sie gleich verwenden wollen:

python3 -c "import os, sys, sysconfig; print('venv:', sys.prefix != sys.base_prefix); print('marker:', os.path.isfile(os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')))"

Blockiert wird die Installation nur, wenn die Ausgabe venv: False und marker: True lautet. In einer virtuellen Umgebung bleibt die Markierung des Basis-Interpreters sichtbar; unsere venv gab deshalb ebenfalls marker: True aus, doch die erste Zeile lautete venv: True, und pip installierte ganz normal.

Welche Systeme liefern die Markierung aus?#

Debian, Ubuntu, Raspberry Pi OS, Arch Linux und Homebrew liefern sie aus; Fedora und die offiziellen Docker-Images nicht.

Debian hat sein Paket für Python 3.11 noch vor der Veröffentlichung von Debian 12 gekennzeichnet, und Ubuntu 23.04 hat genau dieses Paket ausgeliefert. Deshalb zeigen Ubuntu 24.04 LTS und die Ubuntu- oder Debian-Systeme, die viele unter WSL auf Windows betreiben, dieselbe Meldung. Fedora geht einen anderen Weg: Es liefert keine Markierung aus und leitet sudo pip install stattdessen nach /usr/local um.

Lösung 1: Legen Sie eine virtuelle Umgebung für Ihr Projekt an#

Eine virtuelle Umgebung (venv) ist ein Verzeichnis mit eigenem python und eigenem Paketordner, mit dem System-Interpreter verknüpft, aber von dessen Paketen getrennt. Darin überspringt pip die Prüfung nach PEP 668, und nichts, was Sie dort installieren, kann das System berühren.

cd ~/my-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

In unserem Test endete der letzte Befehl mit:

Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0

Die Aktivierung stellt nur das Verzeichnis bin der Umgebung an den Anfang Ihres PATH. Die Python-Dokumentation zu venv nennt den Befehl für jede Shell, unter Windows .venv\Scripts\activate. Sie können die Aktivierung auch weglassen und den Interpreter der Umgebung direkt aufrufen; in Skripten, Cron-Jobs und systemd-Units ist das die sicherere Form:

.venv/bin/python -m pip install requests
.venv/bin/python app.py

Behandeln Sie .venv als Wegwerfordner. Halten Sie ihn aus Git heraus (seit Python 3.13 schreibt venv eine .gitignore in den Ordner), halten Sie Ihre Pakete mit python -m pip freeze > requirements.txt fest und bauen Sie die Umgebung anderswo mit python -m pip install -r requirements.txt neu auf. Eine venv übersteht weder das Verschieben noch das Kopieren auf einen anderen Rechner; legen Sie sie dort neu an.

In VS Code findet die Python-Erweiterung einen Ordner .venv im Arbeitsbereich und bevorzugt ihn. Wählt sie einen anderen Interpreter, führen Sie in der Befehlspalette (Command Palette; Strg+Umschalt+P, auf einem Mac Cmd+Shift+P) den Befehl Python: Select Interpreter (Python: Interpreter auswählen) aus und wählen den Interpreter in .venv; neue Terminals öffnen sich danach mit aktiver Umgebung.

„ensurepip is not available“ unter Debian und Ubuntu#

Debian liefert die Unterstützung für venv in einem eigenen Paket aus, deshalb kann auf einem minimalen Server schon der Befehl python3 -m venv .venv scheitern. Das von Debian angepasste Modul venv gibt dann diese Meldung aus, mit der Versionsnummer Ihres Pythons:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.13-venv

Installieren Sie das Paket (python3-venv zieht das versionsspezifische nach), löschen Sie den halb angelegten Ordner und führen Sie den Befehl erneut aus:

sudo apt install python3-venv
rm -rf .venv
python3 -m venv .venv

Lösung 2: Installieren Sie Kommandozeilen-Tools mit pipx#

Wenn Sie ein Programm statt einer Bibliothek brauchen, etwa einen Formatierer, einen Linter oder einen HTTP-Client, nehmen Sie pipx, das Tool, das die Fehlermeldung selbst vorschlägt. pipx legt für jede Anwendung eine eigene virtuelle Umgebung an und bringt ihre Befehle in Ihren PATH, sodass Tools nie gegenseitig ihre Abhängigkeiten beschädigen.

sudo apt install pipx      # macOS: brew install pipx
pipx ensurepath
pipx install ruff

Öffnen Sie nach pipx ensurepath ein neues Terminal. In unserem Test meldete pipx install ruff die Zeile installed package ruff 0.17.0, und der Befehl ruff funktionierte sofort; später verwalten Sie das Tool mit pipx upgrade ruff und pipx uninstall ruff. Die Installationsanleitung von pipx enthält die Befehle für andere Systeme.

Lösung 3: Verwenden Sie das Paket der Distribution#

Für eine Bibliothek, die ein Systemskript braucht, hat die Distribution womöglich schon ein Paket. Debian, Ubuntu und Raspberry Pi OS benennen Python-Bibliotheken python3-<Name>; Arch verwendet python-<Name>:

sudo apt install python3-requests     # Debian, Ubuntu, Raspberry Pi OS
sudo pacman -S python-requests        # Arch Linux

Diese Versionen erhalten die Sicherheitsupdates der Distribution, sind aber oft älter als die neueste Version auf PyPI. Homebrew paketiert Anwendungen, und seine Dokumentation verweist Sie für Bibliotheken auf eine venv.

Manchmal braucht ein Projekt beides: eine Hardware-Bibliothek aus apt auf einem Raspberry Pi und ein neueres Paket von PyPI. Legen Sie die Umgebung dann mit python3 -m venv --system-site-packages .venv an. Die venv sieht so die Pakete des Systems, und pip installiert trotzdem nur in die venv. In unserem Test landete requests in .venv, während eine bereits installierte Systembibliothek aus dem Systemordner geladen wurde.

Lösung 4: Nutzen Sie uv für Umgebungen und Tools#

Das Tool uv ist ein Paket- und Projektmanager, der mehrere Befehle von pip, venv und pipx durch ein einziges Programm ersetzt. Auch uv respektiert die Markierung: uv pip install --system brach an unserem gekennzeichneten Python mit error: The interpreter at … is externally managed ab, gefolgt vom selben Debian-Text. Sein normaler Ablauf nutzt eine virtuelle Umgebung, sodass der Fehler gar nicht erst auftritt:

uv venv
uv pip install requests
uv tool install ruff

uv venv legt .venv im aktuellen Ordner an, uv pip install installiert ohne Aktivierung dort hinein, und uv tool install ist das Gegenstück zu pipx install. Alle drei funktionierten in unserem Test.

Container und CI-Pipelines#

Die offiziellen python-Images auf Docker Hub kompilieren ihr eigenes Python nach /usr/local und liefern keine Markierung aus, deshalb funktioniert pip install darin wie bisher. Der Fehler tritt auf, wenn ein Dockerfile von einem debian- oder ubuntu-Image ausgeht und Python mit apt installiert. Die Lösung ist dieselbe wie auf dem Laptop: Installieren Sie python3-venv, legen Sie die Umgebung mit RUN python3 -m venv /opt/venv an und ergänzen Sie ENV PATH="/opt/venv/bin:$PATH". Jedes spätere RUN pip install -r requirements.txt und das python des Containers nutzen dann die venv, genau wie nach einer Aktivierung.

CI-Systeme starten oft für jeden Schritt eine neue Shell, sodass eine frühere Aktivierung verloren ist. Rufen Sie in jedem Schritt den Interpreter der Umgebung über seinen Pfad auf (.venv/bin/python -m pip install …, .venv/bin/python -m pytest).

Warum ist --break-system-packages der letzte Ausweg?#

Die Option schaltet den Schutz ab, statt den Konflikt zu lösen, und sie wirkt tatsächlich: In unserer Nachstellung installierte pip install --break-system-packages requests das Paket in das gekennzeichnete Python, ebenso die Umgebungsvariable PIP_BREAK_SYSTEM_PACKAGES=1 und die Zeile break-system-packages = true im Abschnitt [global] einer pip-Konfigurationsdatei. Der Schalter macht die Installation nicht sicher; er entfernt nur die Warnung, und pip kann nun eine Bibliothek aktualisieren oder entfernen, die die eigenen Tools des Systems importieren. Ein späteres Systemupdate kann dann überschreiben, was pip installiert hat.

Die Datei EXTERNALLY-MANAGED zu löschen, hat dieselbe Wirkung für jeden Benutzer und jedes Programm auf dem Rechner. Wenn Sie das Übergehen wirklich brauchen, setzen Sie es dort ein, wo der Schaden begrenzt bleibt, etwa in einem Container, den Sie neu bauen, oder in einer virtuellen Maschine. Nie gehört es in ein Shell-Profil oder eine globale pip-Konfiguration, wo es stillschweigend für jede spätere Installation gilt.

Wie nutzen Sie pip hinter einem Proxy-Server?#

Geben Sie pip die Proxy-URL mit --proxy, über die Variable HTTPS_PROXY oder in seiner Konfigurationsdatei mit. Firmen- und Hochschulnetze lassen Webverkehr oft nur über einen Proxy-Server zu, der Benutzername und Passwort verlangt, und pip meldet fehlende Zugangsdaten nicht als Proxy-Problem. Ohne Zugangsdaten beantwortete unser lokaler Test-Proxy jeden Versuch mit Status 407, und pip gab fünf Wiederholungen aus (vier davon unten entfernt) und ein irreführendes Ergebnis:

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'OSError('Tunnel connection failed: 407 Proxy Authentication Required')': /simple/requests/
ERROR: Could not find a version that satisfies the requirement requests (from versions: none)
ERROR: No matching distribution found for requests

from versions: none bedeutet, dass pip den Paketindex nie erreicht hat, nicht, dass es das Paket nicht gibt. Das pip-Benutzerhandbuch führt alle Optionen auf; diese drei decken die meisten Fälle ab:

# für einen einzelnen Befehl
python -m pip install --proxy http://user:pass@proxy.example.com:8080 requests

# für jeden Befehl in dieser Shell
export HTTPS_PROXY=http://user:pass@proxy.example.com:8080

# nur in der aktiven virtuellen Umgebung gespeichert
python -m pip config --site set global.proxy http://user:pass@proxy.example.com:8080

Alle drei installierten requests über unseren Test-Proxy. Mit --site schrieb pip die Einstellung in die eigene Konfigurationsdatei der venv (pip.conf, unter Windows pip.ini); ohne die Option schreibt pip config set in Ihre Datei auf Benutzerebene, die für jede Umgebung gilt. Enthält das Passwort @, : oder /, müssen diese Zeichen prozentkodiert werden; HTTP 407 Proxy Authentication Required beheben behandelt die Kodierung und andere Fehler mit Zugangsdaten.

Hinter einem Proxy, der HTTPS-Verkehr inspiziert, lautet der nächste Fehler meist CERTIFICATE_VERIFY_FAILED. Ab Version 24.2 vertraut pip zusätzlich den Zertifikaten des Betriebssystems; ein Stammzertifikat der Firma, das die IT im Systemspeicher installiert hat, behebt den Fehler daher oft, und --cert verweist pip auf eine Bundle-Datei. Unable to Get Local Issuer Certificate: Ursachen und Lösung erklärt, wie Sie die Ursachen auseinanderhalten.

Wie senden Sie aus der venv eine erste Anfrage über einen Proxy?#

Ist requests in der venv installiert, braucht eine Anfrage über einen Proxy nur ein Dictionary. Das Skript liest die Proxy-URL aus einer Umgebungsvariablen, sodass die Zugangsdaten nicht im Code stehen:

import os
import sys

import requests

# Endpoint und Zugangsdaten aus Ihrem Proxy-Dashboard
PROXY = os.environ.get("PROXY_URL", "http://user:pass@pr.proxynet.io:8000")
proxies = {"http": PROXY, "https": PROXY}

print("Python:", sys.executable)
try:
    r = requests.get("https://example.com/", proxies=proxies, timeout=15)
    print("Status:", r.status_code)
except requests.exceptions.ProxyError as err:
    print("Proxy error:", err)

Starten Sie es mit .venv/bin/python first_request.py. Über unseren lokalen Test-Proxy zeigte die Zeile Python: den Interpreter in .venv, und die zweite Zeile lautete Status: 200. Mit einem falschen Passwort gab das Skript einen Proxy error aus, der auf Tunnel connection failed: 407 Proxy Authentication Required endete. Mit dem System-python3 gestartet, kam es gar nicht so weit: ModuleNotFoundError: No module named 'requests', weil die Pakete in der venv liegen.

Der Proxy-Typ entscheidet, wie Zielseiten Ihre Anfragen sehen. Ein Residential-Proxy leitet über private Internetanschlüsse in dem Land und der Stadt Ihrer Wahl aus, mit einer neuen Adresse pro Anfrage oder einer Sticky-Sitzung von 1 bis 60 Minuten. Nutzen Sie ihn, um Seiten so zu sehen, wie lokale Besucher sie sehen, im Rahmen der Nutzungsbedingungen und Rate Limits jeder Website.

Ein Datacenter-Proxy gibt Ihnen dedizierte IPv4-Adressen mit Traffic ohne Kontingent; das passt zu gleichmäßigen Aufgaben wie der Prüfung Ihrer eigenen Dienste und APIs aus mehreren Ländern. Wenn Sie Daten senden statt abrufen wollen, behandelt JSON mit Python Requests per POST senden: cURL-Äquivalente json=, Header und die passenden cURL-Befehle.

Wo Ihnen dieser Fehler begegnet#

• Neue Server und VPS-Images mit Debian 12 oder neuer oder mit Ubuntu 24.04, auf denen alte Einrichtungsskripte noch sudo pip install aufrufen.
• Raspberry-Pi-Projekte, die älteren Anleitungen für Sensor- und GPIO-Bibliotheken folgen.
• Macs, auf denen python3 von Homebrew stammt.
• Dockerfiles auf Basis von debian- oder ubuntu-Images, die Python mit apt installieren.
• WSL unter Windows, das Ubuntu oder Debian ausführt.
• CI-Jobs, nachdem das Basis-Image auf ein neueres Release umgestellt wurde.

Häufige Fehler#

• sudo pip install in einer aktivierten venv ausführen. Unter Debian ersetzt sudo den PATH durch eine feste Liste (secure_path), findet das pip des Systems, und der Fehler ist zurück. Eine venv in Ihrem Home-Ordner braucht kein sudo.
• In der venv installieren, aber mit python3 starten. Der System-Interpreter sieht die Pakete der venv nicht und scheitert mit ModuleNotFoundError.
• .venv in Git einchecken oder auf einen anderen Rechner kopieren. Bauen Sie die Umgebung aus requirements.txt neu auf.
• break-system-packages in einer globalen pip-Konfiguration setzen. Das schaltet den Schutz für jede spätere Installation ab.

Entscheidungshilfe#

Häufige Fragen#

Warum funktioniert pip install nach einem Upgrade von Ubuntu oder Debian nicht mehr?#

Ihr neues Release liefert die Markierung EXTERNALLY-MANAGED aus, und pip ab Version 23.0 beachtet sie. Debian 12 und Ubuntu 23.04 waren die ersten Releases mit der Datei, der übliche Auslöser ist daher der Umstieg von Debian 11 oder Ubuntu 22.04.

Ist --break-system-packages sicher?#

Nicht auf einem System, das Sie behalten wollen. Die Option lässt pip Bibliotheken ersetzen oder entfernen, die die eigenen Python-Tools des Betriebssystems importieren. Nutzen Sie sie nur in einem Container oder einer virtuellen Maschine, die Sie neu aufbauen können.

Vermeidet pip install --user den Fehler?#

Nein. Die Prüfung betrachtet den Interpreter, nicht den Benutzerordner, in den die Dateien kämen; deshalb werden auch Installationen mit --user blockiert, wie unser Test bestätigt hat.

Kann ich die Datei EXTERNALLY-MANAGED löschen?#

Ja, aber damit schalten Sie den Schutz für jeden Benutzer und jedes Programm auf dem Rechner ab, genau wie mit einem globalen --break-system-packages, und ein späteres Update des Python-Pakets kann die Datei wiederherstellen. Eine venv löst das Problem ohne diese beiden Nebenwirkungen.

Muss ich die virtuelle Umgebung jedes Mal aktivieren?#

Nein. Die Aktivierung ändert den PATH nur für die aktuelle Shell. Wenn Sie .venv/bin/python aufrufen (unter Windows .venv\Scripts\python.exe), nutzen Sie die Umgebung direkt; für Skripte, Dienste und CI ist das die verlässliche Form.

Warum zeigt pip den Fehler sogar in meiner virtuellen Umgebung?#

Dann ist das pip, das Sie ausgeführt haben, nicht das pip der venv: sudo, ein neues Terminal ohne Aktivierung oder ein Editor-Terminal mit dem System-Interpreter. Führen Sie python -m pip --version aus; der ausgegebene Pfad sollte in .venv liegen.

Fazit#

error: externally-managed-environment ist die Mitteilung des Betriebssystems an pip, dass es am System-Python nichts zu ändern hat. Geben Sie jedem Projekt eine virtuelle Umgebung und jedem Kommandozeilen-Tool über pipx eine eigene, und überlassen Sie das System-Python apt, pacman oder Homebrew. Heben Sie --break-system-packages für Rechner auf, die Sie wegwerfen können. Wenn diese Skripte Websites von anderen Standorten aus erreichen müssen, finden Sie das Passende auf unserer Seite zu Proxy-Diensten.