Zum Inhalt springen
SONOYA.com
Raspberry Pi & Linux

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

Python-Symbol auf dunklem Hintergrund als Sinnbild für Python-Pakete, die unter Linux in einer virtuellen Umgebung statt systemweit installiert werden

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:

Code
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 requestsDebian-Paket mit apt
ein eigenes Projekt mit festen Paketversionenvirtuelle Umgebung mit venv
ein Kommandozeilenprogramm wie httpie oder yt-dlp benutzenpipx

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:

Code
apt search python3-requests

Taucht das Paket auf, installierst Du es wie jede andere Software:

Code
sudo apt install python3-requests

Damit 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:

Code
sudo apt install python3-venv

Wechsle danach in den Ordner Deines Projekts, hier ~/projekt, und erstelle die Umgebung im Unterordner .venv:

Code
mkdir -p ~/projekt
cd ~/projekt
python3 -m venv .venv

Aktiviere sie jetzt, damit python und pip in diesem Terminal auf die Umgebung zeigen:

Code
source .venv/bin/activate

Vor Deiner Eingabeaufforderung steht nun (.venv). Daran erkennst Du, dass die Umgebung aktiv ist. Ab jetzt funktioniert pip install ohne Fehlermeldung:

Code
pip install requests

Hat 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:

Code
python3 -m venv --system-site-packages .venv

So 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:

Code
sudo apt install pipx
pipx ensurepath

Der 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:

Code
pipx install httpie

Im 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:

Code
/home/pi/projekt/.venv/bin/python /home/pi/projekt/skript.py

Ersetze 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 created oder ensurepip is not available: Das Modul fehlt. Installiere es mit sudo apt install python3-venv und lösche den halb angelegten Ordner mit rm -rf .venv, bevor Du es erneut versuchst.
  • Der Fehler kommt trotz Umgebung: Die Umgebung ist nicht aktiv, oder Du hast sudo pip benutzt. sudo startet das System-Python. In einer virtuellen Umgebung brauchst Du kein sudo, sie gehört Deinem Benutzer.
  • ModuleNotFoundError im Cronjob: Der Aufruf nutzt python3 statt des Interpreters aus .venv/bin/. Trag den vollen Pfad ein wie oben gezeigt.
  • pipx-Befehl wird nicht gefunden: pipx ensurepath wurde ausgeführt, aber die Shell noch nicht neu gestartet. Melde Dich ab und wieder an.
  • Permission denied beim 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.