pip: „externally-managed-environment“ richtig lösen
pip install meldet externally-managed-environment? So installierst Du Python-Pakete auf Raspberry Pi, Debian und Ubuntu sauber mit apt, venv oder pipx.
Von Nathan Base
Du willst auf dem Raspberry Pi, unter Debian oder Ubuntu schnell ein Paket mit pip install nachinstallieren, und statt einer Installation bekommst Du einen roten Block mit error: externally-managed-environment. Das ist kein Defekt, sondern eine bewusste Sperre Deiner Linux-Distribution. Hier erfährst Du, warum es sie gibt, welcher der drei sauberen Wege für Deinen Fall der richtige ist und wie Du ein Skript mit eigenen Paketen anschließend auch aus Cron oder systemd heraus startest.
Getestet habe ich alle Befehle in einem Container mit Debian 13.7 (Trixie), Python 3.13 und pip 25.1. Raspberry Pi OS Trixie basiert auf genau dieser Version, und Ubuntu verhält sich seit 23.04 gleich.
Was die Meldung bedeutet
Die vollständige Ausgabe sieht so aus, gekürzt auf das Wesentliche:
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.Dein System-Python gehört dem Paketmanager apt. Viele Programme des Betriebssystems sind selbst in Python geschrieben und verlassen sich auf genau die Versionen, die Debian mitliefert. Würde pip dort systemweit eine neuere oder ältere Bibliothek ablegen, könnte das beim nächsten Update Systemwerkzeuge zerlegen, und apt wüsste nicht einmal davon. Deshalb legt Debian die Datei /usr/lib/python3.13/EXTERNALLY-MANAGED ab. Findet pip sie, verweigert es die Installation. Das Verfahren ist im Python-Standard PEP 668 beschrieben.
Die Sperre gilt auch für sudo pip install und für pip install --user. Du umgehst sie also nicht mit mehr Rechten, sondern nur mit einem der drei Wege unten.
Welcher Weg für Deinen Fall passt
Die Entscheidung hängt davon ab, was Du vorhast:
| Du willst … | Weg |
|---|---|
eine bekannte Bibliothek für ein kleines Skript, etwa requests | Debian-Paket mit apt |
| ein eigenes Projekt mit festen Paketversionen | virtuelle Umgebung mit venv |
ein Kommandozeilenprogramm wie httpie oder yt-dlp benutzen | pipx |
Weg 1: Das Debian-Paket nehmen
Viele verbreitete Bibliotheken gibt es fertig als Paket. Der Name folgt dem Muster python3-<name>. Ob es eines gibt, findest Du mit einer Suche heraus:
apt search python3-requestsTaucht das Paket auf, installierst Du es wie jede andere Software:
sudo apt install python3-requestsDamit steht die Bibliothek allen Python-Skripten auf dem System zur Verfügung und bekommt Sicherheitsupdates zusammen mit dem Rest des Systems. Der Nachteil: Du bekommst die Version, die Debian ausgewählt hat. In meinem Test war das requests 2.32.3, während auf PyPI schon 2.34 erhältlich war. Für die meisten Hausautomations- und Pi-Skripte spielt das keine Rolle.
Weg 2: Eine virtuelle Umgebung für Dein Projekt
Brauchst Du eine bestimmte Version, ein Paket, das Debian nicht anbietet, oder mehrere Pakete aus einer requirements.txt, legst Du eine virtuelle Umgebung an. Das ist ein Ordner mit einer eigenen Kopie von pip und einem eigenen Paketverzeichnis, das vom System getrennt ist. Unter Debian und Ubuntu musst Du das Modul dafür einmal nachinstallieren. Auf Raspberry Pi OS schadet der Befehl nicht, falls es schon da ist:
sudo apt install python3-venvWechsle danach in den Ordner Deines Projekts, hier ~/projekt, und erstelle die Umgebung im Unterordner .venv:
mkdir -p ~/projekt
cd ~/projekt
python3 -m venv .venvAktiviere sie jetzt, damit python und pip in diesem Terminal auf die Umgebung zeigen:
source .venv/bin/activateVor Deiner Eingabeaufforderung steht nun (.venv). Daran erkennst Du, dass die Umgebung aktiv ist. Ab jetzt funktioniert pip install ohne Fehlermeldung:
pip install requestsHat Dein Projekt eine Liste mit Abhängigkeiten, installierst Du sie in einem Rutsch mit pip install -r requirements.txt. Ob alles stimmt, zeigt Dir which python: Die Ausgabe muss auf /home/<benutzer>/projekt/.venv/bin/python zeigen. Mit deactivate verlässt Du die Umgebung wieder.
Wichtig: Leg die Umgebung pro Projekt an und nicht als eine große Sammelumgebung für alles. Geht etwas schief, löschst Du einfach den Ordner .venv und erstellst ihn neu, ohne das System anzufassen.
Hardware-Bibliotheken auf dem Raspberry Pi
Auf dem Pi gibt es einen Sonderfall. Bibliotheken wie picamera2 oder gpiozero kommen mit Raspberry Pi OS als Systempakete und sind mit der Hardware verzahnt. Eine normale virtuelle Umgebung sieht sie nicht. Die Raspberry-Pi-Dokumentation nennt dafür die Option --system-site-packages, mit der die Umgebung zusätzlich auf die installierten Systempakete zugreifen darf:
python3 -m venv --system-site-packages .venvSo nutzt Dein Skript die mitgelieferten Hardware-Bibliotheken und kann trotzdem eigene Pakete per pip in die Umgebung installieren.
Weg 3: Programme mit pipx installieren
Manchmal willst Du gar keine Bibliothek, sondern ein fertiges Programm für die Kommandozeile, das zufällig in Python geschrieben ist. Dafür ist pipx gedacht. Es legt für jedes Programm automatisch eine eigene, versteckte Umgebung an und stellt nur den Befehl bereit:
sudo apt install pipx
pipx ensurepathDer zweite Befehl trägt ~/.local/bin in Deinen Suchpfad ein. Öffne danach ein neues Terminal oder melde Dich per SSH neu an, damit die Änderung greift. Jetzt installierst Du Programme so:
pipx install httpieIm Test lagen danach die Befehle http und https in ~/.local/bin und ließen sich direkt aufrufen. Mit pipx upgrade-all bringst Du später alle so installierten Programme auf den neuesten Stand, und pipx list zeigt Dir, was installiert ist. Die pipx-Dokumentation beschreibt weitere Befehle.
Das Skript aus Cron und systemd starten
Hier stolpern viele: Das Skript läuft im Terminal, aber nicht als Cronjob oder Dienst. Der Grund ist, dass Cron und systemd die Umgebung nicht aktivieren. Das brauchst Du aber auch nicht. Es reicht, den Python-Interpreter aus der Umgebung mit vollem Pfad aufzurufen, denn er findet seine Pakete von selbst:
/home/pi/projekt/.venv/bin/python /home/pi/projekt/skript.pyErsetze pi durch Deinen Benutzernamen und skript.py durch den Namen Deines Skripts. Genau diese Zeile trägst Du hinter die Zeitangabe in die Crontab ein. Wie Cronjobs grundsätzlich funktionieren, zeigt die Anleitung: Cronjobs unter Raspberry Pi OS einrichten. Für einen dauerhaft laufenden Dienst gehört dieselbe Zeile hinter ExecStart= in die Unit-Datei, so wie im Artikel Eigenen systemd-Dienst anlegen: Skripte dauerhaft starten beschrieben.
Warum Du —break-system-packages nicht nutzen solltest
In vielen Antworten im Netz steht der Tipp, einfach --break-system-packages anzuhängen oder die Datei EXTERNALLY-MANAGED zu löschen. Beides funktioniert im ersten Moment, schaltet aber genau den Schutz ab, der Dein System vor kaputten Abhängigkeiten bewahrt. Die Folgen zeigen sich oft erst Wochen später, wenn ein apt upgrade scheitert oder ein Systemwerkzeug nicht mehr startet. Der Name der Option ist ernst gemeint. In einem Wegwerf-Container ist sie vertretbar, auf Deinem Pi oder Server nicht.
Wenn es nicht klappt
The virtual environment was not successfully createdoderensurepip is not available: Das Modul fehlt. Installiere es mitsudo apt install python3-venvund lösche den halb angelegten Ordner mitrm -rf .venv, bevor Du es erneut versuchst.- Der Fehler kommt trotz Umgebung: Die Umgebung ist nicht aktiv, oder Du hast
sudo pipbenutzt.sudostartet das System-Python. In einer virtuellen Umgebung brauchst Du keinsudo, sie gehört Deinem Benutzer. ModuleNotFoundErrorim Cronjob: Der Aufruf nutztpython3statt des Interpreters aus.venv/bin/. Trag den vollen Pfad ein wie oben gezeigt.pipx-Befehl wird nicht gefunden:pipx ensurepathwurde ausgeführt, aber die Shell noch nicht neu gestartet. Melde Dich ab und wieder an.Permission deniedbeim Anlegen der Umgebung: Du stehst in einem Ordner, der Dir nicht gehört, etwa unter/opt. Leg das Projekt in Deinem Home-Verzeichnis an oder passe die Rechte an, wie es der Artikel Linux-Dateirechte: chmod, chown und Permission denied erklärt.
Fazit
Die Meldung externally-managed-environment schützt Dein System und lässt sich in fast allen Fällen in einer Minute lösen: Für bekannte Bibliotheken nimmst Du das Paket aus apt, für eigene Projekte eine virtuelle Umgebung und für Kommandozeilenprogramme pipx. Wer sich angewöhnt, jedes Projekt mit python3 -m venv .venv zu beginnen, sieht die Meldung danach praktisch nie wieder. Arbeitest Du zusätzlich am Mac, gilt dort dasselbe Prinzip, wie der Artikel Python am Mac mit Homebrew installieren und in VS Code nutzen zeigt.
Weiterlesen.
-
Raspberry Pi & LinuxAnleitung: Cronjobs unter Raspberry Pi OS einrichten
Cronjobs unter Raspberry Pi OS Trixie einrichten: Zeitzone setzen, crontab verstehen, Bash- und Python-Scripts samt venv starten und Fehler protokollieren.
Nathan Base -
Raspberry Pi & LinuxEigenen systemd-Dienst anlegen: Skripte dauerhaft starten
Python-Skript oder Bot als systemd-Dienst: startet beim Booten und nach Absturz neu, schreibt Logs. Mit getesteter Unit-Vorlage und Timer.
Nathan Base -
Raspberry Pi & LinuxLinux-Dateirechte: chmod, chown und Permission denied
Was rwx, 755 und 644 bedeuten und wie Du „Permission denied“ unter Linux und auf dem Raspberry Pi mit chmod, chown und Gruppen löst, ohne chmod 777.
Nathan Base -
Raspberry Pi & LinuxLinux-Festplatte voll: große Dateien finden mit ncdu
No space left on device? So findest Du unter Linux mit df, du und ncdu die Speicherfresser, räumst sicher auf und löst auch den Fall gelöschter Dateien.
Nathan Base -
Raspberry Pi & LinuxLinux-Befehle für Einsteiger: die 30 wichtigsten
Die wichtigsten Linux-Befehle für Ubuntu, Debian und Raspberry Pi OS mit Beispielen: Dateien, Ordner, Rechte, Pakete, Prozesse, Netzwerk und Hilfe.
Nathan Base -
Raspberry Pi & Linuxjournalctl: Fehler unter Linux in den Logs finden
Mit journalctl findest Du heraus, warum ein Dienst streikt oder der Pi neu startet: nach Dienst, Zeit und Priorität filtern, Journal dauerhaft speichern.
Nathan Base