Was ist eine virtuelle Umgebung in Python?

Warum Projekte sich ohne Trennung gegenseitig stören

Ohne virtuelle Umgebung landet jede Installation mit pip im selben Paketverzeichnis des Interpreters. Braucht ein Projekt eine Bibliothek in Version 1 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. Mit einer Umgebung je Projekt hat jedes seinen eigenen Satz an Paketen in genau den Versionen, die es braucht.

Unter Linux kommt hinzu, dass die Distribution eigene Python-Pakete installiert und Systemwerkzeuge davon abhängen. Viele aktuelle Distributionen, darunter Debian und Ubuntu, markieren ihr System-Python deshalb nach PEP 668 als extern verwaltet. Ein pip install außerhalb einer Umgebung bricht dann mit der Meldung „externally-managed-environment“ ab. Die virtuelle Umgebung ist der vorgesehene Ausweg, nicht das Umgehen der Sperre.

Virtuelle Umgebung erstellen, aktivieren und verlassen

Im Projektordner legst du die Umgebung mit einem Befehl an, aktivierst sie, installierst Pakete und verlässt sie wieder. Welcher Befehl die Umgebung aktiviert, hängt von der Shell ab:

Unter Linux und macOS sieht der ganze Ablauf so aus:

python3 -m venv .venv            # Umgebung im Ordner .venv anlegen
source .venv/bin/activate        # aktivieren, der Prompt zeigt jetzt (.venv)
python -m pip install requests   # Paket nur in diese Umgebung installieren
deactivate                       # Umgebung verlassen

Verlassen funktioniert in jeder Shell mit deactivate. Schließt du das Terminal, ist die Umgebung ebenfalls nicht mehr aktiv, denn die Aktivierung gilt immer nur für die aktuelle Shell. Bei conda heißt der Befehl dagegen conda deactivate.

Unter Windows legst du die Umgebung mit py -m venv .venv an. Verweigert PowerShell das Aktivierungsskript, erlaubt Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser lokale Skripte für deinen Benutzer. Unter Debian und Ubuntu fehlt das Modul venv in der Grundinstallation manchmal, dann installierst du das Paket python3-venv nach.

Was im Ordner .venv steckt

Eine virtuelle Umgebung ist keine Kopie von Python. Sie besteht aus der Datei pyvenv.cfg, die auf die zugrunde liegende Python-Installation verweist, einem Ordner bin (unter Windows Scripts) mit einem Verweis auf den Interpreter, pip und den Aktivierungsskripten, und einem eigenen Paketverzeichnis site-packages. Python erkennt beim Start an der pyvenv.cfg, dass es in einer Umgebung läuft, und sucht Pakete nur dort.

Aktivieren bedeutet technisch nur, dass der Ordner bin der Umgebung vorne in den Suchpfad PATH gestellt und die Variable VIRTUAL_ENV gesetzt wird. Deshalb kannst du das Aktivieren auch weglassen und den Interpreter direkt aufrufen, etwa mit .venv/bin/python skript.py. Das Ergebnis ist dasselbe.

Der Name .venv ist eine Konvention, kein Zwang. Viele Werkzeuge, darunter Editoren wie Visual Studio Code und der Paketmanager uv, suchen aber genau diesen Ordner im Projekt und nutzen ihn automatisch. Seit Python 3.13 legt venv in der Umgebung außerdem eine eigene .gitignore an, damit der Ordner nicht versehentlich im Repository landet.

Wie venv, pip, Poetry und uv zusammenspielen

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

Poetry, pipenv und uv fassen beide Aufgaben zusammen. Sie lesen die gewünschten Pakete aus einer Projektdatei, meist der pyproject.toml, lösen die Abhängigkeiten auf, schreiben das Ergebnis in eine Lock-Datei und legen die virtuelle Umgebung selbst an. uv legt sie als .venv im Projektordner ab, Poetry und pipenv standardmäßig in einem zentralen Verzeichnis. Unter der Haube bleibt es in allen Fällen eine gewöhnliche virtuelle Umgebung, nur dass du sie nicht mehr von Hand anlegst und aktivierst.

Fehler, die immer wieder auftauchen

Der Klassiker ist die vergessene Aktivierung. Das Paket ist installiert, der Import schlägt trotzdem mit ModuleNotFoundError fehl, weil die Installation in einer anderen Umgebung oder im System-Python gelandet ist. Die schnelle Kontrolle ist which python unter Linux und macOS beziehungsweise where python unter Windows. Gewöhn dir außerdem python -m pip install statt pip install an, dann gehört pip garantiert zu dem Interpreter, den du gerade meinst.

Zweiter Dauerbrenner ist die verschobene oder kopierte Umgebung. Die Skripte in bin enthalten absolute Pfade, eine Umgebung lässt sich deshalb weder in einen anderen Ordner verschieben noch auf einen anderen Rechner kopieren. Dasselbe gilt nach einem Update der zugrunde liegenden Python-Version, wenn der alte Interpreter entfernt wurde. In allen Fällen ist die Lösung, die Umgebung zu löschen und aus der Abhängigkeitsliste neu aufzubauen.