Python: Für jedes Projekt eine virtuelle Umgebung erstellen und verwenden

Eine virtuelle Umgebung ist ein Verzeichnis, das einer Python-Installation zugeordnet ist und einen eigenen Paketsatz verwaltet. Mit dem Standardmodul venv lässt sich eine solche Umgebung erstellen. Standardmäßig werden ihre Pakete von den Paketen der Basisinstallation isoliert. Dadurch kann jedes Projekt eigene Abhängigkeiten haben, statt zwangsläufig eine einzige Paketsammlung auf dem gesamten Computer gemeinsam zu nutzen. Offizielle venv-Dokumentation

Stellen Sie sich zwei Projekte vor: Das eine benötigt eine bestimmte Version einer Bibliothek, das andere hängt von einer anderen Version ab. Werden beide Versionen in derselben globalen Umgebung installiert, kann es zu Inkompatibilitäten kommen. Mit einer separaten Umgebung für jedes Projekt kann jedes seine Pakete installieren, ohne den Paketsatz des anderen zu verändern. Der wichtigste Vorteil ist die Isolierung von Abhängigkeiten, nicht eine vollständige Trennung vom System oder die Garantie, dass das Projekt auf jedem Computer identisch läuft.

venv gehört seit Python 3.3 zur Python-Standardbibliothek. Die Umgebung basiert auf einer vorhandenen Python-Installation, dem sogenannten Basis-Python, und verwendet die Interpreterversion, mit der sie erstellt wurde. Das Erstellen einer Umgebung installiert daher nicht automatisch eine beliebige Python-Version, die das Projekt benötigt: Zuerst muss der passende Interpreter verfügbar sein. Offizielle venv-Dokumentation

Öffnen Sie vor dem Erstellen der Umgebung ein Terminal und prüfen Sie, ob Python verfügbar ist. Die Befehlsnamen können je nach Betriebssystem und Installationsmethode variieren. Unter macOS und vielen Linux-Distributionen probiert man häufig python3 --version; unter Windows py --version oder python --version. Wird ein Befehl nicht erkannt, probieren Sie die anderen verfügbaren Optionen aus und prüfen Sie, welchen Interpreter sie jeweils aufrufen. Diese Anleitung setzt nicht voraus, dass auf jedem Computer derselbe Befehl gilt.

Erstellen oder öffnen Sie den Projektordner und führen Sie die Befehle von dort aus. .venv ist ein üblicher Name für das Umgebungsverzeichnis: Der Punkt am Anfang sorgt dafür, dass manche Dateimanager es als verborgen anzeigen, ändert aber nicht die Funktionsweise von Python. Auch der Python Packaging User Guide empfiehlt, Pakete für ein Projekt in einer virtuellen Umgebung zu installieren. Python Packaging User Guide

Prüfen Sie außerdem, ob Sie Schreibrechte für den Ordner haben und ob der ausgewählte Interpreter der gewünschte ist. Wenn mehrere Installationen vorhanden sind, hilft die Ausgabe von --version, eine unerwartete Auswahl zu erkennen. Die Umgebung übernimmt die Python-Version, mit der sie erstellt wurde. Daher sollte diese Entscheidung vor der Installation von Paketen getroffen werden.

Der Ort, von dem aus Sie den Befehl ausführen, ist wichtig, denn .venv wird im aktuellen Ordner erstellt. Wenn das Verzeichnis im Projekt liegt, lässt sich leichter erkennen, zu welchem Projekt die Umgebung gehört. Ist dort bereits ein Verzeichnis namens .venv vorhanden, prüfen Sie dessen Inhalt und Zweck, bevor Sie am selben Pfad eine weitere Umgebung erstellen. Wählen Sie den Interpreter bewusst aus: Auf einem Computer mit mehreren Python-Versionen verrät der Befehlsname allein nicht, welche Installation verwendet wird.

Das Modul wird als Python-Modul ausgeführt: -m venv weist den Interpreter an, venv aufzurufen, und .venv ist das Verzeichnis, das erstellt wird. Verwenden Sie den Befehl, der zu Ihrer Installation passt:

• Windows: py -m venv .venv (wenn der Launcher py nicht verfügbar ist, versuchen Sie python -m venv .venv).
• macOS oder Linux: python3 -m venv .venv (falls python3 nicht vorhanden ist, prüfen Sie, ob python auf den gewünschten Interpreter verweist).

Laut Dokumentation werden beim Erstellen das Zielverzeichnis und Konfigurationsdateien angelegt. Die ausführbaren Dateien innerhalb der Umgebung sind je nach Plattform unterschiedlich angeordnet: Unter Windows liegen sie in Scripts, auf Unix-ähnlichen Systemen wie macOS und Linux in bin. Offizielle venv-Dokumentation Beim Erstellen wird normalerweise keine ausführliche Bestätigung ausgegeben; Sie können das Ergebnis überprüfen, indem Sie im Projektordner nach .venv suchen. Schlägt der Befehl fehl, lesen Sie die vollständige Meldung, bevor Sie es erneut versuchen: Sie kann auf einen fehlenden Interpreter, fehlende Schreibrechte oder eine unvollständige Umgebung hinweisen. Gehen Sie nicht davon aus, dass ein erneutes Ausführen desselben Befehls die Ursache behebt. Wenn das Zielverzeichnis schon existiert, prüfen Sie es, bevor Sie entscheiden, was zu tun ist, statt Dateien zu löschen, deren Zweck Sie nicht kennen. Der Aufbau des Befehls bleibt auf den Plattformen ähnlich, doch der Interpreterbefehl und die Verzeichnisstruktur des Ergebnisses können abweichen. Das Umgebungsverzeichnis im Projekt zu belassen, erleichtert auch die späteren Aktivierungsbefehle. Nach dem Erstellen lässt sich die Umgebung mit dem Skript für Ihre Shell aktivieren. Das Erstellen installiert noch keine Projektpakete; die Installation ist ein eigener Schritt nach der Aktivierung. Es ist hilfreich, das Erstellen der Umgebung, das Installieren von Paketen und das Ausführen des Projekts als getrennte Schritte zu betrachten. Wenn Sie nicht wissen, welcher Interpreter aufgerufen wurde, prüfen Sie erneut die Python-Version und die Installation, bevor Sie fortfahren. So vermeiden Sie, die Projektumgebung mit einer unerwarteten Python-Version zu erstellen. Eine bestimmte Bestätigungsausgabe ist nicht erforderlich, damit das Erstellen erfolgreich war: Das Vorhandensein des Verzeichnisses und seiner Umgebungsdateien ist die praktische Prüfung. Eine Fehlermeldung sollten Sie hingegen verstehen, bevor Sie fortfahren. Durch die Prüfung des Ordners und der Meldung lässt sich ein Erstellungsfehler von späteren Problemen beim Aktivieren oder Installieren von Paketen unterscheiden. Der Name .venv ist üblich, aber nicht vorgeschrieben. In diesen Beispielen ist er der gewählte Zielname; verwenden Sie deshalb in den folgenden Befehlen denselben Namen. Wenn Sie einen anderen Namen wählen, müssen auch die Aktivierungspfade dazu passen. Die folgenden Beispiele setzen voraus, dass Sie .venv beibehalten haben. Dadurch bleiben die Befehle vom Erstellen über das Aktivieren bis zum Deaktivieren einheitlich. Die Umgebung bleibt der Python-Installation zugeordnet, mit der sie erstellt wurde; deshalb ist die vorherige Auswahl des Interpreters wichtig. Der Befehl erstellt eine lokale Umgebung im aktuellen Projektordner. Er kopiert nicht das ganze Betriebssystem und ersetzt nicht die Python-Basisinstallation. Diese Grenzen helfen dabei, den Begriff „isoliert“ in diesem Zusammenhang richtig zu verstehen. Als Nächstes aktivieren Sie die Umgebung in dem Terminal, in dem Sie arbeiten möchten. Öffnen Sie später ein anderes Terminal, muss die Umgebung dort möglicherweise erneut aktiviert werden. Das ist erwartetes Verhalten und bedeutet nicht, dass die Umgebung gelöscht wurde. Die Dateien bleiben in .venv, bis Sie sie selbst entfernen.**

venv stellt damit einen lokalen Arbeitsbereich für Pakete eines Projekts bereit, der mit dem ausgewählten Python-Interpreter erstellt wurde. Das plattformspezifische Verzeichnis für ausführbare Dateien erklärt, warum sich die Aktivierungspfade unterscheiden, obwohl das Erstellungsverfahren ähnlich ist. Sobald Sie geprüft haben, dass das Verzeichnis vorhanden ist, verwenden Sie den für Ihr Terminal passenden Aktivierungsbefehl.

Aktivieren Sie die erstellte Umgebung mit dem Skript, das zur verwendeten Shell passt. Führen Sie unter macOS und Linux im Projektordner source .venv/bin/activate aus. Unter Windows hängt der Befehl vom Terminal ab: In PowerShell verwenden Sie .venv\Scripts\Activate.ps1, in der Eingabeaufforderung .venv\Scripts\activate.bat. Fügen Sie beim Kopieren keinen führenden Leerraum hinzu.

Nach der Aktivierung zeigt das Terminal am Anfang der Eingabeaufforderung meist (.venv) an. Das ist ein praktischer Hinweis, aber nicht die einzige mögliche Prüfung. Anschließend können Sie eine Bibliothek installieren, zum Beispiel mit python -m pip install paketname. Wenn Sie pip über das aktive python aufrufen, wird die Installation leichter dem ausgewählten Interpreter zugeordnet. Die Packaging-Dokumentation beschreibt die Installation mit pip in einer virtuellen Umgebung. Python Packaging User Guide

Führen Sie das Programm mit python datei.py aus und ersetzen Sie datei.py durch den tatsächlichen Dateinamen. Mit python --version können Sie die Version des verwendeten Interpreters überprüfen; den Pfad erhalten Sie auch mit python -c "import sys; print(sys.executable)". Installieren Sie Pakete und führen Sie das Programm mit derselben aktiven Umgebung aus: So sinkt das Risiko, ein Paket in einer Installation zu installieren und das Projekt mit einer anderen auszuführen.

Der shell-spezifische Aktivierungsbefehl ändert die aktuelle Terminalsitzung, sodass Befehle wie python den Interpreter der Umgebung verwenden. Aktivieren Sie die Umgebung deshalb in dem Terminal, in dem Sie Pakete installieren und das Projekt ausführen möchten. Wenn Sie ein weiteres Terminal öffnen, nehmen Sie nicht an, dass es bereits dieselbe Umgebung verwendet: Aktivieren Sie sie auch dort und prüfen Sie anschließend die Eingabeaufforderung oder den Interpreterpfad. Diese kurze Prüfung kann erklären, warum ein Paket scheinbar fehlt, obwohl ein Installationsbefehl erfolgreich war. Verwenden Sie beim Ausführen den tatsächlichen Dateinamen und bleiben Sie im Projektordner, sofern das Projekt kein anderes Arbeitsverzeichnis erfordert. Die Beispiele sind Terminalbefehle und kein Text, der in die Python-Datei eingefügt werden soll.

Um die aktive Umgebung zu verlassen, geben Sie deactivate ein und drücken Sie die Eingabetaste. Der Befehl beendet die Verwendung der virtuellen Umgebung in diesem Terminal; er löscht weder die Dateien in .venv noch deinstalliert er deren Pakete. Um am Projekt weiterzuarbeiten, öffnen Sie ein Terminal im Projektordner und wiederholen Sie den passenden Aktivierungsbefehl für Windows, macOS oder Linux. Offizielle venv-Dokumentation

Scheitert die Aktivierung in PowerShell mit einer Meldung zur Skriptausführung, ändern Sie nicht blind die Sicherheitseinstellungen des Computers. Sie können ein anderes kompatibles Terminal wie die Eingabeaufforderung verwenden und die Windows-Python-Dokumentation zur installationsspezifischen Konfiguration heranziehen. Microsoft Learn: Python unter Windows Erscheint „Befehl nicht gefunden“, prüfen Sie zuerst, ob Sie sich im Projektordner befinden, .venv vorhanden ist und Sie den Pfad für Ihre Plattform korrekt eingegeben haben.

Meldet pip, ein Paket sei bereits installiert, aber das Programm kann es nicht finden, prüfen Sie sys.executable und den Installationspfad: Möglicherweise verwendet das Terminal nicht die erwartete Umgebung. Scheitert das Erstellen, weil venv nicht verfügbar ist, prüfen Sie die Python-Installation und die zugehörigen Komponenten des Systems. Was genau zu tun ist, hängt davon ab, wie Python installiert wurde. Löschen Sie nicht als ersten Schritt eine globale Installation.

Untersuchen Sie bei der Fehlersuche die einzelnen Schritte getrennt, statt mehrere Einstellungen gleichzeitig zu ändern. Prüfen Sie zuerst den Ordner und das Umgebungsverzeichnis, danach den Interpreterpfad und führen Sie schließlich den betreffenden Befehl erneut aus. Fehlt (.venv) in der Eingabeaufforderung, kann das ein Hinweis sein; sys.executable zeigt jedoch direkt, welchen Interpreter der aktuelle python-Befehl aufruft. Das Deaktivieren ist umkehrbar: Es ändert den aktiven Kontext des Terminals, nicht die im Projekt gespeicherten Dateien. Sobald Sie den fehlerhaften Schritt gefunden haben, verwenden Sie den Aktivierungsbefehl für Ihr Betriebssystem und Ihre Shell, statt einen Befehl für ein anderes Terminal zu übernehmen.

Eine virtuelle Umgebung ist ein lokales Isolierungswerkzeug und keine Projektspezifikation. Wenn eine andere Person den Paketsatz rekonstruieren muss, halten Sie die Abhängigkeiten in einer vom Projekt verwalteten Datei fest. Bei einfachen Projekten mit pip besteht ein gängiger Ablauf darin, mit python -m pip freeze > requirements.txt eine Liste zu erzeugen und sie in einer anderen Umgebung mit python -m pip install -r requirements.txt zu installieren. Die Liste gibt die zu diesem Zeitpunkt installierten Pakete und Versionen wieder. Prüfen Sie, ob sie sich zum Teilen und Pflegen eignet, bevor Sie sie als vollständige Projektbeschreibung behandeln.

Nehmen Sie .venv nicht in das Repository auf: Das Verzeichnis ist in der Regel lokal, möglicherweise groß und an das ursprüngliche System und den ursprünglichen Interpreter gebunden. Nehmen Sie stattdessen die Dateien auf, die das Projekt und seine Abhängigkeiten beschreiben, und richten Sie sich nach dem Arbeitsablauf des Teams. Wenn Sie das Projekt auf einen anderen Computer klonen oder kopieren, erstellen Sie dort mit der passenden Python-Version eine neue Umgebung und installieren die gespeicherten Abhängigkeiten.

Die Isolierung durch venv hat bewusst gesetzte Grenzen. Es handelt sich weder um eine virtuelle Maschine noch um einen Container: venv ersetzt nicht die Installation des Interpreters, kopiert nicht zwangsläufig das ganze Betriebssystem und beseitigt keine Plattformunterschiede. Da die Basisinstallation außerhalb der Umgebung bleibt, ersetzt eine virtuelle Umgebung außerdem keine Sicherheits-, Aktualisierungs- und Versionsverwaltungspraxis. Der alltägliche Ablauf ist einfach: zum Projekt wechseln, .venv erstellen, aktivieren, Abhängigkeiten installieren, das Programm ausführen und die Umgebung am Ende deaktivieren.

Die Umgebung selbst ist nicht die Aufzeichnung, die eine andere Person zur Wiederherstellung des Paketsatzes benötigt. Eine Abhängigkeitsdatei enthält diese Informationen in einer Form, die sich beim Erstellen einer frischen Umgebung verwenden lässt. Der Befehl freeze listet die installierten Pakete und Versionen zum Zeitpunkt seiner Ausführung auf. Das Ergebnis sollte deshalb geprüft und gepflegt werden; es ist nicht automatisch eine vollständige Beschreibung aller Projektaspekte. Auch das Auslassen von .venv im Repository verhindert, dass ein lokales Verzeichnis mit der gemeinsam gepflegten Projektbeschreibung verwechselt wird. Erstellen Sie die Umgebung auf einem anderen Computer neu, indem Sie eine geeignete Python-Installation auswählen und die Abhängigkeiten dort installieren. So bleiben Projektdateien, Abhängigkeitsangaben und die lokale Laufzeitumgebung klar voneinander getrennt. Zugleich wird die zentrale Grenze deutlich: Die Isolierung von Paketen ist nützlich, macht unterschiedliche Computer und Betriebssysteme aber nicht identisch.