Abhängigkeiten je Projekt

Was ist eine virtuelle Umgebung in Python?

venv, Virtual Environment

Eine virtuelle Umgebung ist ein Ordner, in dem Python ein eigenes Verzeichnis für installierte Pakete und eigene Startskripte anlegt, sodass diese Pakete nur für ein einzelnes Projekt gelten. Die Systeminstallation und andere Projekte bleiben davon unberührt.

Zwei Python-Projekte auf demselben Rechner brauchen selten dieselbe Version einer Bibliothek, und ohne getrennte Umgebungen gewinnt immer die zuletzt installierte.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

Standardweg: python -m venv, seit Python 3.3 eingebaut
Aktivierung: Über das activate-Skript der Umgebung
Gehört nicht: Ins Repository, nur die Abhängigkeitsliste
Verwechselt mit: Container und conda-Umgebungen

Warum Projekte sich sonst gegenseitig stören

Ohne Trennung landet jede Installation mit pip im selben systemweiten Verzeichnis. Sobald ein Projekt eine Bibliothek in Version 1 braucht und das nächste dieselbe Bibliothek in Version 2, gewinnt die zuletzt installierte, und das andere Projekt bricht an einer Stelle ab, die niemand angefasst hat. Unter Linux kommt hinzu, dass die Distribution eigene Python-Pakete in dieses Verzeichnis legt und Systemwerkzeuge davon abhängen. Neuere Distributionen unterbinden deshalb ein pip install außerhalb einer Umgebung und weisen in der Fehlermeldung auf die Regelung aus PEP 668 hin.

Der Aufruf python -m venv .venv legt die Umgebung an, source .venv/bin/activate aktiviert sie in der aktuellen Shell, unter Windows liegt das entsprechende Skript im Ordner Scripts. Aktivieren heißt technisch nur, dass dieser Ordner vorne im Suchpfad steht, deshalb wirkt es pro Terminal und nicht systemweit. Du kannst das Skript auch weglassen und direkt .venv/bin/python aufrufen, das Ergebnis ist dasselbe.

Wie venv, pip, Poetry und uv zusammenspielen

venv baut die Umgebung, pip füllt sie. Die Liste der Pakete hältst du in einer requirements.txt fest, erzeugt mit pip freeze, und stellst sie auf einem anderen Rechner mit pip install -r requirements.txt wieder her. Diese Datei mischt allerdings die von dir gewollten Pakete mit allem, was diese nachziehen. Deshalb führen viele Projekte zwei Dateien, eine gepflegte Liste der direkten Abhängigkeiten und eine erzeugte mit exakten Versionen.

Poetry, pipenv und uv fassen beide Aufgaben zusammen. Alle drei lesen die gewünschten Pakete aus einer Projektdatei, lösen die Abhängigkeiten auf, schreiben das Ergebnis in eine Lock-Datei und legen die Umgebung im Hintergrund an, ohne dass du sie von Hand aktivierst. Der Unterschied im Alltag ist vor allem die Zahl der Befehle: Statt Umgebung anlegen, aktivieren und installieren genügt ein Aufruf, und das Ergebnis ist auf jedem Rechner bis zur Patch-Version gleich.

Fehler, die immer wieder auftauchen

Der Klassiker ist die vergessene Aktivierung. Das Paket ist installiert, der Import schlägt trotzdem fehl, weil die Installation in einer anderen Umgebung gelandet ist. Die schnelle Kontrolle ist which python beziehungsweise where python, und im Zweifel ersetzt du pip install durch python -m pip install. Dann gehört pip garantiert zu dem Interpreter, den du gerade meinst.

Zweiter Dauerbrenner ist die eingecheckte Umgebung. Der Ordner .venv gehört nicht ins Repository, er enthält absolute Pfade und plattformabhängige Binärdateien und lässt sich anderswo nicht sinnvoll wiederverwenden. Versioniert wird die Beschreibung der Abhängigkeiten, nicht ihr Ergebnis. Im Container stellt sich die Frage etwas anders, dort liefert schon das Image die Trennung, viele Teams legen aber trotzdem eine Umgebung an, damit der Pfad zu den Paketen unabhängig vom Basis-Image gleich bleibt.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

Nicht verwechseln

Virtuelle Umgebung und was oft damit gleichgesetzt wird

Virtuelle Umgebung gegen Container

Ein Container isoliert das ganze Betriebssystem samt Systembibliotheken, eine virtuelle Umgebung nur die Python-Pakete. Wenn ein Paket eine C-Bibliothek in einer bestimmten Version voraussetzt, hilft venv nicht weiter, ein passendes Image dagegen schon.

Virtuelle Umgebung gegen conda-Umgebung

conda verwaltet neben Python-Paketen auch Bibliotheken außerhalb der Python-Welt und die Interpreter-Version selbst, bezieht sie aber aus eigenen Quellen. Bei viel Numerik ist das ein Vorteil, im Mischbetrieb mit pip entstehen leicht Umgebungen, in denen niemand mehr sagen kann, woher ein Paket stammt.

Virtuelle Umgebung gegen pyenv

pyenv wechselt die Python-Version, legt aber keine Trennung der Pakete an. Beides ergänzt sich: pyenv bestimmt, welcher Interpreter läuft, die virtuelle Umgebung, welche Pakete er sieht.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

In der Praxis

Der Ärger fängt an, wenn zwei Projekte dieselbe Bibliothek brauchen

Ein älteres Projekt läuft nur mit einer bestimmten alten Version einer Bibliothek, das neue braucht die aktuelle. Ohne getrennte Umgebungen gewinnt die zuletzt installierte, und der Schaden zeigt sich erst beim Start des anderen Projekts. Zu jedem Projektordner gehört deshalb eine eigene Umgebung, und in die Versionsverwaltung gehört nur die Liste der Abhängigkeiten, nie der Ordner selbst.

Die häufigste Verwirrung ist das Aktivieren. Ein frisch geöffnetes Terminal, eine Aufgabe im Editor oder ein Dienst, den systemd startet, kennt die Umgebung nicht von allein, und plötzlich fehlt ein Paket, das nachweislich installiert ist. In Skripten und Diensten hilft es, den Interpreter direkt aus dem bin-Verzeichnis der Umgebung aufzurufen, statt sich auf die Aktivierung zu verlassen.

Für den Betrieb leistet die Umgebung nicht dasselbe wie ein Container. Sie trennt Python-Pakete, nicht aber Systembibliotheken, Compiler oder die Python-Version selbst. Erwartet ein Paket eine C-Bibliothek, die auf dem Zielsystem fehlt, bricht die Installation dort ab, egal wie sauber die Umgebung angelegt ist.

Virtuelle Umgebung lernen

Wie du ein Projekt sauber aufsetzt, Abhängigkeiten festhältst und eigene Pakete baust, behandeln die Python-Trainings für Entwicklerteams an durchgehenden Beispielen.

Eine reproduzierbare Umgebung ist auch die Grundlage für verlässliche Testläufe, worum es in den Trainings zu automatisierten Testläufen ausführlich geht.

Kurse, die Virtuelle Umgebung behandeln

Häufige Fragen

Brauche ich für jedes kleine Skript eine eigene Umgebung?

Für ein Skript, das nur die Standardbibliothek benutzt, nicht. Sobald eine einzige externe Abhängigkeit dazukommt, lohnt sich der eine Befehl, weil sich sonst immer mehr Pakete in der Systeminstallation ansammeln. Für Werkzeuge, die du überall auf der Kommandozeile brauchst, gibt es pipx, das jedem Werkzeug im Hintergrund eine eigene Umgebung gibt.

Gehört der Ordner .venv ins Git-Repository?

Nein. Trag ihn in die .gitignore ein und versioniere stattdessen die Abhängigkeitsdatei samt Lock-Datei. Damit baut jede Person im Team dieselbe Umgebung mit einem Befehl neu auf, statt mehrere hundert Megabyte Binärdateien zu übertragen.

Was mache ich, wenn eine Umgebung kaputt ist?

Löschen und neu anlegen. Eine virtuelle Umgebung ist ein Wegwerfartikel, alles Wichtige steht in der Abhängigkeitsdatei. Wenn schon der Neuaufbau scheitert, liegt der Fehler dort und nicht in der Umgebung.

Persönlich für dich da