Python Virtuelle Umgebungen (venv)

Eine virtuelle Umgebung ist ein in sich geschlossenes Verzeichnis, das eine eigene Kopie eines Python-Interpreters und seinen eigenen site-packages-Ordner enthält. Pakete, die du innerhalb einer virtuellen Umgebung installierst, sind vollständig von deinem System-Python und jeder anderen Umgebung auf deinem Rechner isoliert — so können zwei Projekte auf verschiedene Versionen derselben Bibliothek angewiesen sein, ohne jemals in Konflikt zu geraten.

Dieses Kapitel erklärt, warum virtuelle Umgebungen wichtig sind, wie man sie mit dem integrierten venv-Modul erstellt und aktiviert, wie man Abhängigkeiten mit pip verwaltet und welchen Arbeitsablauf die meisten Python-Projekte befolgen.

Warum virtuelle Umgebungen wichtig sind

Stell dir vor, du hast zwei Projekte auf demselben Rechner:

• Projekt A benötigt requests==2.28.0
• Projekt B benötigt requests==2.31.0

Wenn du beide Versionen in die globale Python-Umgebung installierst, überschreibt pip einfach die zuerst installierte Version. Ein Projekt wird nicht mehr funktionieren. Virtuelle Umgebungen lösen dieses Problem, indem jedes Projekt sein eigenes isoliertes site-packages-Verzeichnis erhält, sodass beide Versionen nebeneinander existieren, ohne sich gegenseitig zu beeinflussen.

Weitere praktische Vorteile:

Eine virtuelle Umgebung erstellen

Python 3.3 und höher enthält venv in der Standardbibliothek — keine Installation erforderlich.

python -m venv .venv

Damit wird ein .venv-Verzeichnis im aktuellen Ordner erstellt. Der Name .venv ist eine verbreitete Konvention (der führende Punkt versteckt das Verzeichnis auf Unix-ähnlichen Systemen), aber du kannst jeden beliebigen Namen verwenden — env, venv oder sogar einen projektspezifischen Namen.

Was venv innerhalb von .venv erstellt:

.venv/
├── bin/           # Python interpreter + activation scripts (Linux/macOS)
│   ├── activate
│   ├── python -> python3
│   └── pip
├── include/
├── lib/
│   └── python3.x/
│       └── site-packages/   # Installed packages go here
└── pyvenv.cfg               # Records the Python version and base prefix

Unter Windows unterscheidet sich die Struktur leicht — bin/ heißt Scripts/ und Pfadtrennzeichen sind Backslashes.

Eine bestimmte Python-Version auswählen

Wenn du mehrere Python-Versionen installiert hast, gib den Interpreter explizit an:

python3.11 -m venv .venv

Oder unter Windows:

py -3.11 -m venv .venv

Die pyvenv.cfg-Datei innerhalb der Umgebung speichert, welcher Interpreter verwendet wurde, sodass die Umgebung immer mit dieser Version läuft.

Die Umgebung aktivieren

Das Erstellen der Umgebung verwendet sie nicht automatisch. Du musst sie aktivieren, wodurch das bin/-Verzeichnis der Umgebung deinem PATH vorangestellt wird, damit python und pip auf die Kopien der Umgebung verweisen.

macOS und Linux:

source .venv/bin/activate

Windows (Eingabeaufforderung):

.venv\Scripts\activate.bat

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Nach der Aktivierung zeigt die Shell-Eingabeaufforderung üblicherweise den Umgebungsnamen in Klammern:

(.venv) $ python --version
Python 3.12.3
(.venv) $ which python
/your/project/.venv/bin/python

Jeder pip install-Befehl, den du während der aktiven Umgebung ausführst, installiert in .venv/lib/.../site-packages/ und niemals in das System-Python.

Deaktivieren

Wenn du mit der Arbeit am Projekt fertig bist oder zu einer anderen Umgebung wechseln möchtest:

deactivate

Die Shell-Eingabeaufforderung kehrt zur normalen Anzeige zurück und python verweist wieder auf den System-Interpreter.

Pakete innerhalb einer virtuellen Umgebung installieren

Mit aktiver Umgebung verwendest du pip ganz normal:

pip install requests flask

Bestätige, dass die Pakete am richtigen Ort gelandet sind:

pip show requests

Die Zeile Location: in der Ausgabe sollte auf dein .venv-Verzeichnis zeigen.

Prüfen, was installiert ist

pip list

Eine frisch erstellte Umgebung enthält typischerweise nur pip und setuptools. Alles andere, was du siehst, wurde explizit von dir (oder einer requirements-Datei) installiert.

Abhängigkeiten speichern und wiederherstellen

Eine requirements-Datei exportieren

Sobald deine Umgebung eingerichtet ist, frier die exakten Paketversionen ein, damit jeder sie reproduzieren kann:

pip freeze > requirements.txt

Eine typische requirements.txt sieht so aus:

certifi==2024.2.2
charset-normalizer==3.3.2
flask==3.0.3
idna==3.6
requests==2.31.0
urllib3==2.2.1

Commit requirements.txt zur Versionskontrolle. Commit das .venv-Verzeichnis selbst nicht — füge es zu .gitignore hinzu.

Aus einer requirements-Datei wiederherstellen

Auf einem neuen Rechner oder in einem frischen Clone:

python -m venv .venv
source .venv/bin/activate        # or the Windows equivalent
pip install -r requirements.txt

Damit wird eine Umgebung identisch zu der eingefrorenen neu erstellt.

Standardmäßiger Projektablauf

Die meisten Python-Projekte folgen dieser Reihenfolge:

# 1. Clone the repository
git clone https://github.com/example/myproject.git
cd myproject

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
source .venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Work on the project ...

# 6. When you add a new package, update the requirements file
pip install newpackage
pip freeze > requirements.txt

Was zur .gitignore hinzufügen

Committe das Umgebungsverzeichnis niemals zur Versionskontrolle — es enthält kompilierte Binärdateien, ist plattformspezifisch und kann Dutzende von Megabyte groß sein. Füge eines dieser Muster zu deiner .gitignore hinzu:

# Virtual environment
.venv/
venv/
env/

Committe nur requirements.txt (oder pyproject.toml + requirements.txt). Das ist alles, was jemand braucht, um die Umgebung von Grund auf neu aufzubauen.

venv im Vergleich zu anderen Tools

venv ist die integrierte Lösung und für die meisten Anwendungsfälle ausreichend. Du wirst möglicherweise auch diesen Alternativen begegnen:

Für die meisten Einsteiger und einfache Projekte ist python -m venv die richtige Wahl — es wird mit Python mitgeliefert und erfordert keine zusätzliche Installation.

Häufige Fehler und Lösungen

„python: command not found" beim Erstellen der Umgebung

Bei einigen Linux-Distributionen wird Python 3 als python3 aufgerufen, nicht als python:

python3 -m venv .venv

PowerShell verweigert die Ausführung des Aktivierungsskripts

Standardmäßig blockiert Windows PowerShell unsignierte Skripte. Aktiviere die Skriptausführung für den aktuellen Benutzer:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Führe dann das Aktivierungsskript erneut aus.

Pakete installiert, aber import schlägt fehl

Du hast wahrscheinlich vergessen, die Umgebung zu aktivieren. Führe aus:

source .venv/bin/activate

Versuche den Import dann erneut. Du kannst mit which python (macOS/Linux) oder where python (Windows) bestätigen, welches Python aktiv ist.

Die Umgebung verweist auf eine gelöschte Python-Installation

Wenn du Python aktualisierst und die alte Version entfernst, brechen venv-Verknüpfungen. Erstelle die Umgebung einfach neu:

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Kurzübersichtstabelle

Verwandte Kapitel

• Python pip — der vollständige Leitfaden zum Installieren, Aktualisieren und Entfernen von Paketen
• Python Modules — verstehe, wie das Importsystem von Python funktioniert
• Python Packages — organisiere deinen eigenen Code in installierbare Pakete

Übungen