Schlagwort: Setup

Tutorial: pyenv auf macOS – mehrere Python-Versionen einfach verwalten

Wer mit Python arbeitet, stößt früher oder später auf Versionskonflikte. In diesem Tutorial zeige ich Dir Schritt für Schritt, wie Du mit pyenv auf macOS mehrere Python-Versionen sauber installierst und pro Projekt verwaltest. Ideal für Einsteiger, Studierende und alle, die ihr Python-Setup endlich ordentlich aufräumen wollen.

Tutorial: pyenv auf macOS – mehrere Python-Versionen einfach verwalten

Die Welt der KI dreht sich schnell – und oft stolpert man schon bei Python

Die Welt der KI dreht sich schnell. Neue Bibliotheken erscheinen gefühlt jede Woche, Tutorials beziehen sich mal auf Python 3.11, mal auf Python 3.12, und irgendwo taucht dann schon wieder Python 3.13 auf. Wenn man mehrere Projekte parallel ausprobiert, kommt schnell ein typisches Problem auf: Ein Skript läuft auf dem einen Rechner, auf dem anderen nicht. Ein Paket lässt sich plötzlich nicht installieren. Und im schlimmsten Fall hat man am Ende gar nicht mehr im Blick, welche Python-Version eigentlich gerade aktiv ist.

Gerade auf dem Mac ist das ein Thema, weil macOS selbst oft schon mit einer Python-Version oder Python-bezogenen Systempfaden arbeitet. Die sollte man nach Möglichkeit nicht anfassen. Gleichzeitig möchten viele von uns neue Tools testen, alte Projekte weiter pflegen oder ein Tutorial Schritt für Schritt nachbauen, ohne jedes Mal das gesamte System umzubauen.

Genau hier kommt pyenv ins Spiel. pyenv auf GitHub

Mit pyenv kannst Du:

  • mehrere Python-Versionen parallel installieren,
  • pro Projekt eine eigene Python-Version festlegen,
  • zwischen Versionen sauber wechseln,
  • und Dir viel Frust mit kaputten Setups sparen.

In diesem Artikel gehen wir das Ganze Schritt für Schritt durch. Du brauchst  kein Terminal-Profi zu sein. Wenn Du schon einmal einen Befehl kopiert und eingefügt hast, kommst Du hier gut mit.

Wenn Du danach nicht nur Dein Python-Setup aufräumen, sondern auch direkt mit lokaler KI auf dem Mac experimentieren willst, schau Dir auch den passenden Artikel zu Ollama und Open WebUI an.

Warum mehrere Python-Versionen überhaupt sinnvoll sind

Wenn man gerade erst mit Python beginnt, wirkt die Idee von mehreren Python-Versionen erst einmal unnötig kompliziert. Man denkt: „Ich installiere Python einmal und dann ist gut.“ Für ganz einfache Einstiege kann das sogar reichen. Spätestens bei mehreren Projekten oder Tutorials ändert sich die Lage aber.

Typische Situationen sind zum Beispiel:

  • Ein älteres Projekt wurde mit Python 3.10 oder 3.11 erstellt.
  • Ein neues Tutorial verwendet bereits Python 3.12 oder 3.13.
  • Eine bestimmte Bibliothek unterstützt eine Python-Version noch nicht vollständig.
  • Ein KI- oder Data-Science-Paket macht unter einer Version Probleme,
    unter einer anderen aber nicht.

Das Problem ist dabei nicht, dass Python „schlecht“ wäre. Im Gegenteil: Python entwickelt sich sehr aktiv weiter. Genau deshalb ist es aber sinnvoll, verschiedene Versionen gezielt zu verwalten.

Das typische Chaos ohne pyenv

Ohne ein Tool wie pyenv passiert oft Folgendes:

  • Man installiert Python über eine Webseite.
  • Dann noch eine andere Version über Homebrew.
  • Vielleicht kommt später noch Miniconda oder Anaconda dazu.
  • Im Terminal zeigt python etwas anderes an als python3.
  • In VS Code läuft plötzlich nicht dieselbe Version wie im Terminal.

Das führt schnell zu Verwirrung. Und wenn man dann noch mit virtuellen  Umgebungen arbeitet, wird es endgültig unübersichtlich.

Warum pyenv eine gute Lösung ist

pyenv bringt Ordnung in dieses Durcheinander.

Die Idee ist einfach:

  • pyenv installiert Python-Versionen sauber getrennt voneinander.
  • Du kannst festlegen, welche Version standardmäßig verwendet werden soll.
  • In einem bestimmten Projektordner kannst Du eine lokale Version setzen.
  • Temporär kannst Du für eine Terminal-Sitzung auch eine andere Version aktivieren.

Das Schöne daran: Du musst nicht jedes Mal Python deinstallieren oder neu installieren, nur weil Du an einem anderen Projekt arbeitest.

Was ist pyenv genau?

pyenv ist ein leichtgewichtiges Werkzeug zur Verwaltung von Python-Versionen. Es ersetzt Python nicht, sondern hilft Dir dabei, die verschiedenen installierten Versionen sinnvoll zu organisieren.

Wichtig ist, zwei Dinge auseinanderzuhalten:

  • Python-Versionen verwalten → dafür ist pyenv da.
  • Pakete innerhalb eines Projekts verwalten → dafür nutzt man meistens venv, pip oder in manchen Fällen Conda.

Das heißt: pyenv löst nicht jedes Problem allein. Aber es löst einen sehr wichtigen Teil des Problems, nämlich die Frage: Welche Python-Version soll hier überhaupt laufen?

Was pyenv nicht ist

Damit keine falschen Erwartungen entstehen:

  • pyenv ist kein Ersatz für pip.
  • pyenv ist kein kompletter Paketmanager für Bibliotheken.
  • pyenv ist keine virtuelle Umgebung an sich.

In der Praxis funktioniert die Kombination aus pyenv + venv für viele Leute
auf dem Mac hervorragend:

  • pyenv bestimmt die Python-Version.
  • venv kapselt die Projekt-Abhängigkeiten.

Das ist sauber, verständlich und für viele Tutorials absolut ausreichend.

Voraussetzungen auf macOS

Für dieses Tutorial brauchst Du keinen besonderen Spezialrechner. Ein normaler Mac reicht völlig aus.

Das solltest Du mitbringen

  • einen Mac mit aktuellem macOS,
  • Zugriff auf das Terminal,
  • Homebrew installiert,
  • und die Bereitschaft, ein paar Befehle einzugeben.

Falls Homebrew noch nicht installiert ist, kannst Du das mit dem offiziellen Befehl nachholen:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Danach solltest Du prüfen, ob Homebrew verfügbar ist:

brew --version

Xcode Command Line Tools

Für das Kompilieren mancher Python-Versionen sind die Xcode Command Line Tools hilfreich oder sogar notwendig. Falls sie fehlen, kannst Du sie so installieren:

xcode-select --install

Wenn macOS meldet, dass sie bereits installiert sind, ist alles gut.

Schritt 1: pyenv mit Homebrew installieren

Jetzt installieren wir pyenv.

Homebrew aktualisieren

Bevor Du loslegst, ist ein kurzes Update sinnvoll:

brew update

pyenv installieren

Danach installierst Du pyenv:

brew install pyenv

Optional kannst Du zusätzlich pyenv-virtualenv installieren. Für diesen Artikel ist das nicht zwingend nötig, weil wir später auch mit venv arbeiten können. Wenn Du es trotzdem direkt mitnehmen willst:

brew install pyenv-virtualenv

Installation prüfen

Nach der Installation kannst Du testen, ob pyenv grundsätzlich vorhanden ist:

pyenv --version

Wenn an dieser Stelle noch eine Fehlermeldung erscheint, ist das meistens kein Drama. Sehr häufig fehlt nur die Einbindung in die Shell-Konfiguration. Genau das machen wir als Nächstes.

Schritt 2: pyenv in die zsh einbinden

Auf modernen Macs ist zsh normalerweise die Standard-Shell. Damit pyenv sauber funktioniert, muss es in Deiner ~/.zshrc eingetragen werden.

Einträge in die ~/.zshrc schreiben

Füge diese Zeilen hinzu:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

Wenn Du auch pyenv-virtualenv installiert hast, kannst Du zusätzlich diese Zeile ergänzen:

echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

Shell neu laden

Danach lädst Du die Konfiguration neu:

source ~/.zshrc

Alternativ kannst Du das Terminal einfach schließen und erneut öffnen.

Funktion testen

Jetzt sollten diese Befehle funktionieren:

pyenv --version
pyenv versions
pyenv install --list | tail -n 20

pyenv versions zeigt zunächst oft noch keine installierten Python-Versionen an. Das ist normal. Wir haben zwar pyenv installiert, aber noch kein zusätzliches Python darüber eingerichtet.

Schritt 3: Verfügbare Python-Versionen anzeigen

Mit pyenv kannst Du viele Python-Versionen installieren. Um die verfügbaren Varianten zu sehen, nutzt Du:

pyenv install --list

Die Liste ist lang. Wirklich lang. Deshalb ist es oft praktischer, sie zu filtern. Zum Beispiel nach 3.12:

pyenv install --list | grep " 3.12"

Oder nach 3.11:

pyenv install --list | grep " 3.11"

Für Einsteiger ist es meistens sinnvoll, eine stabile und weit verbreitete Version zu wählen, etwa eine aktuelle Python-3.12-Version oder – wenn ein Projekt es verlangt – Python 3.11.

Schritt 4: Eine Python-Version installieren

Nehmen wir als Beispiel Python 3.12.2. Der genaue Patch-Stand kann sich im Laufe der Zeit ändern. Du kannst also auch eine andere aktuelle Unterversion wählen.

pyenv install 3.12.2

Die Installation kann ein paar Minuten dauern. Dabei lädt pyenv den Quellcode herunter und baut die Version für Deinen Rechner. Auf neueren Macs geht das meist recht angenehm, auf älteren Geräten braucht man manchmal etwas Geduld.

Wenn Du zusätzlich noch eine zweite Version für ältere Projekte installieren möchtest, zum Beispiel 3.11.9, geht das genauso:

pyenv install 3.11.9

Danach kannst Du Dir alle installierten Versionen anzeigen lassen:

pyenv versions

Die Ausgabe könnte dann ungefähr so aussehen:

* system
  3.11.9
  3.12.2

system steht dabei für die Python-Version, die außerhalb von pyenv auf Deinem System verfügbar wäre.

Schritt 5: Der Unterschied zwischen global, local und shell

Das ist der wichtigste Teil des Artikels. Wenn Du diese drei Begriffe verstehst, wird pyenv plötzlich sehr logisch.

global

Mit global setzt Du die Python-Version, die standardmäßig in Deinem Benutzerkonto verwendet werden soll.

Zum Beispiel:

pyenv global 3.12.2

Danach ist Python 3.12.2 Deine Standardversion – sofern kein Projekt lokal etwas anderes festlegt.

Prüfen kannst Du das mit:

python --version
pyenv version

local

Mit local legst Du eine Python-Version für ein bestimmtes Projektverzeichnis fest. Das ist im Alltag oft die nützlichste Funktion.

Beispiel:

mkdir mein-python-projekt
cd mein-python-projekt
pyenv local 3.11.9

Dadurch wird im aktuellen Ordner eine Datei namens .python-version angelegt. Immer wenn Du Dich in diesem Verzeichnis befindest, verwendet pyenv automatisch Python 3.11.9.

Das ist extrem praktisch, weil Du nicht ständig manuell umschalten musst.

shell

Mit shell setzt Du eine Version nur für die aktuelle Terminal-Sitzung.

pyenv shell 3.12.2

Sobald Du das Terminal schließt oder die Sitzung änderst, ist diese Einstellung wieder weg. Das ist hilfreich für schnelle Tests, aber für dauerhafte Projektarbeit ist local meist sinnvoller.

Die Priorität merken

Wenn mehrere Einstellungen zusammenkommen, gilt vereinfacht diese Reihenfolge:

  1. shell
  2. local
  3. global
  4. system

Das heißt: Eine temporäre shell-Einstellung überschreibt eine lokale Projektversion, und diese überschreibt wiederum die globale Standardversion.

Schritt 6: Ein echtes Projekt mit pyenv anlegen

Jetzt setzen wir das Ganze einmal praktisch um.

Projektordner erstellen

mkdir ~/Desktop/python-demo-mit-pyenv
cd ~/Desktop/python-demo-mit-pyenv

Lokale Python-Version festlegen

pyenv local 3.12.2

Python-Version kontrollieren

python --version

Wenn alles passt, solltest Du jetzt die gerade gesetzte Version sehen.

Virtuelle Umgebung erstellen

Auch wenn pyenv bereits die Python-Version verwaltet, ist eine virtuelle Umgebung pro Projekt weiterhin sinnvoll. Damit trennst Du die installierten Pakete sauber voneinander.

python -m venv .venv

Virtuelle Umgebung aktivieren

source .venv/bin/activate

Danach kannst Du prüfen, welche Python-Version in der virtuellen Umgebung aktiv ist:

python --version
which python

Paket installieren

Zum Beispiel:

pip install requests

Oder für viele KI-/ML-Beispiele:

pip install numpy pandas matplotlib

Damit hast Du bereits ein sehr sauberes Setup:

  • pyenv sorgt für die richtige Python-Version.
  • .venv kapselt die Projekt-Abhängigkeiten.

Genau so arbeitet man im Alltag angenehm und reproduzierbar.

Ein Mini-Beispiel: Zwei Projekte, zwei  Python-Versionen

Nehmen wir an, Du hast zwei Projekte:

  • Projekt A nutzt Python 3.11.9
  • Projekt B nutzt Python 3.12.2

Dann könntest Du das so einrichten:

mkdir ~/Desktop/projekt-a
cd ~/Desktop/projekt-a
pyenv local 3.11.9
python -m venv .venv
source .venv/bin/activate
python --version

Und für das zweite Projekt:

mkdir ~/Desktop/projekt-b
cd ~/Desktop/projekt-b
pyenv local 3.12.2
python -m venv .venv
source .venv/bin/activate
python --version

Der große Vorteil: Wenn Du später in den jeweiligen Ordner wechselst, stellt pyenv automatisch die richtige Python-Version bereit. Du musst nicht jedes Mal überlegen, welches Projekt welche Version braucht.

Nützliche pyenv-Befehle für den Alltag

Hier ist eine kleine Übersicht mit Befehlen, die man wirklich häufig braucht.

Installierte Versionen anzeigen

pyenv versions

Aktive Version anzeigen

pyenv version

Pfad zur aktuell verwendeten Python-Datei anzeigen

pyenv which python

Globale Version setzen

pyenv global 3.12.2

Lokale Version im Projekt setzen

pyenv local 3.11.9

Temporäre Version für die aktuelle Shell setzen

pyenv shell 3.12.2

Eine installierte Version wieder entfernen

pyenv uninstall 3.11.9

Nach Änderungen die internen Shim-Dateien aktualisieren

In vielen Fällen macht pyenv das automatisch. Falls etwas merkwürdig wirkt, kann dieser Befehl helfen:

pyenv rehash

Typische Fehler und wie Du sie löst

Selbst mit einem sauberen Tool wie pyenv läuft nicht immer alles sofort glatt. Die gute Nachricht: Die häufigsten Probleme sind überschaubar.

Fehler:
pyenv: command not found

Das deutet fast immer darauf hin, dass pyenv nicht richtig in Deine Shell eingebunden ist.

Prüfe:

  • Wurden die Zeilen wirklich in ~/.zshrc eingefügt?
  • Hast Du source ~/.zshrc ausgeführt?
  • Hast Du das Terminal neu gestartet?

Wenn Du unsicher bist, kannst Du die Datei mit einem Editor öffnen und nachsehen.

Fehler: python --version zeigt nicht die erwartete Version

Prüfe zuerst:

pyenv version
pyenv which python
which python

Wichtige Hinweise:

  • Vielleicht bist Du noch in einem Ordner mit lokaler .python-version.
  • Vielleicht ist eine virtuelle Umgebung aktiv.
  • Vielleicht überschreibt eine shell-Einstellung gerade Deine globale Version.

Gerade am Anfang hilft es, diese drei Ebenen bewusst zu unterscheiden.

Fehler beim Installieren einer Python-Version

Wenn pyenv install 3.x.x scheitert, helfen oft diese Schritte:

xcode-select --install
brew update
brew upgrade

Manchmal fehlen auch Bibliotheken, die zum Kompilieren gebraucht werden. In hartnäckigen Fällen können diese Pakete nützlich sein:

brew install openssl readline sqlite3 xz zlib tcl-tk

Nicht jede Installation braucht das. Aber wenn eine Python-Version nicht sauber gebaut werden kann, lohnt sich ein Blick in diese Richtung.

Warum Du die macOS-System-Python besser in Ruhe lässt

Viele Einsteiger sehen irgendwo auf dem System Python-Dateien und denken: „Dann nutze ich eben einfach die.“ Das kann funktionieren, ist langfristig aber selten die beste Idee.

Besser ist:

  • die Systembestandteile in Ruhe lassen,
  • eigene Python-Versionen mit pyenv verwalten,
  • und pro Projekt mit virtuellen Umgebungen arbeiten.

So vermeidest Du Überraschungen nach macOS-Updates und hältst Dein Setup sauber.

pyenv oder Conda – was ist besser?

Diese Frage taucht oft auf, gerade im Machine-Learning-Umfeld.

Wann pyenv stark ist

pyenv ist besonders angenehm, wenn Du:

  • klassisches Python lernen möchtest,
  • mehrere Python-Versionen parallel brauchst,
  • Web-, Skript- oder kleinere Datenprojekte hast,
  • ein leichtgewichtiges Setup bevorzugst.

In Kombination mit venv ist das für viele Leserinnen und Leser eine sehr gute Standardlösung.

Wann Conda sinnvoll sein kann

Conda ist oft praktisch, wenn Du:

  • viele wissenschaftliche Pakete mit nativen Abhängigkeiten nutzt,
  • aus dem Data-Science- oder Research-Bereich kommst,
  • komplexere Umgebungen bequem verwalten willst.

Das heißt aber nicht, dass Conda automatisch „besser“ ist. Es ist einfach ein anderer Ansatz.

Meine pragmatische Empfehlung

Wenn Du gerade Ordnung in Dein Python-Setup auf dem Mac bringen willst, ist pyenv + venv ein hervorragender Start:

  • leicht verständlich,
  • gut dokumentiert,
  • flexibel,
  • und für die meisten Tutorials mehr als ausreichend.

Wenn Du später tiefer in Data Science oder spezielle ML-Setups gehst, kannst Du Dir Conda immer noch anschauen.

pyenv und Entwicklungsumgebungen wie VS Code

Viele arbeiten nicht nur im Terminal, sondern auch mit VS Code oder einer anderen IDE. Das ist völlig normal. Wichtig ist nur, dass die IDE dieselbe Python-Version verwendet wie Dein Projekt.

In VS Code solltest Du deshalb nach dem Anlegen Deiner .venv bewusst den passenden Interpreter auswählen.

Ein typischer sauberer Workflow ist:

  1. Projektordner öffnen
  2. pyenv local setzen
  3. .venv anlegen
  4. virtuelle Umgebung aktivieren
  5. in VS Code den Interpreter aus .venv auswählen

Damit stimmen Terminal, Projekt und Editor in der Regel sauber überein.

Eine kurze Checkliste zum Nachmachen

Wenn Du das Tutorial kompakt nachbauen willst, kannst Du Dich an dieser Reihenfolge orientieren:

Schnellstart

brew update
brew install pyenv
xcode-select --install

Dann ~/.zshrc ergänzen:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"

Shell neu laden:

source ~/.zshrc

Python installieren und global setzen:

pyenv install 3.12.2
pyenv global 3.12.2
python --version

Projekt einrichten:

mkdir mein-projekt
cd mein-projekt
pyenv local 3.12.2
python -m venv .venv
source .venv/bin/activate

Damit steht bereits ein sehr brauchbares Python-Setup.

Fazit

pyenv ist eines dieser Tools, die am Anfang ein bisschen technisch wirken, im Alltag aber unglaublich viel Ruhe ins System bringen. Gerade auf macOS, wo schnell mehrere Python-Versionen, Tutorials und Projektanforderungen zusammenkommen, ist das Gold wert.

Wenn Du mit Python arbeitest, lohnt es sich sehr, die Begriffe global,
local und shell einmal sauber zu verstehen. Danach wird vieles plötzlich deutlich logischer. Und in Kombination mit venv bekommst Du ein Setup, das sowohl für Einsteiger als auch für fortgeschrittene Projekte richtig gut  funktioniert.

Besonders praktisch ist das für:

  • Lernprojekte,
  • Uni- und Studienarbeiten,
  • Webentwicklung,
  • Automatisierungsskripte,
  • und natürlich auch für Machine-Learning-Tutorials mit unterschiedlichen Abhängigkeiten.

Wenn Du bisher immer nur „irgendein Python“ auf dem Mac installiert hattest, probier pyenv ruhig aus. Der Unterschied zeigt sich meist schon beim zweiten oder dritten Projekt. Plötzlich ist es nicht mehr chaotisch, sondern planbar.

Und genau das ist am Ende oft wichtiger als die neueste Library: ein Setup, das stabil ist, nachvollziehbar bleibt und Dir nicht ständig im Weg steht.