Virtuelle Python-Umgebungen lösen eines der häufigsten Probleme in der Python-Entwicklung: Abhängigkeitskonflikte zwischen Projekten. Wenn Projekt A Django 4.2 und Projekt B Django 5.0 benötigt, macht eine globale Installation eines der beiden kaputt. Virtuelle Umgebungen erstellen isolierte Python-Installationen, in denen jedes Projekt seine eigenen Pakete, eigene Versionen und ein eigenes pip hat — vollständig unabhängig voneinander und vom System-Python. Dieser Leitfaden deckt alles ab, von der ersten Umgebung bis hin zu Produktionsdeployment-Mustern.

Voraussetzungen

  • Python 3.3 oder neuer installiert (python3 --version zum Prüfen)
  • Grundlegende Vertrautheit mit der Kommandozeile (Terminal, Shell oder PowerShell)
  • Ein Texteditor oder eine IDE für Python-Entwicklung
  • pip verfügbar (standardmäßig ab Python 3.4 enthalten)

Virtuelle Umgebungen mit venv erstellen

venv ist Pythons integriertes Modul zum Erstellen virtueller Umgebungen. Es ist seit Python 3.3 enthalten und erfordert keine zusätzliche Installation.

Grundlegende Erstellung

# Virtuelle Umgebung im Verzeichnis .venv erstellen
python3 -m venv .venv

# Auf manchen Systemen muss zunächst das venv-Paket installiert werden
# Debian/Ubuntu:
sudo apt install python3-venv

# Überprüfen, ob die Umgebung erstellt wurde
ls .venv/
# Ausgabe: bin/  include/  lib/  pyvenv.cfg

Der Verzeichnisname .venv ist eine Konvention — man kann ihn beliebig benennen, aber .venv ist die gängigste Wahl. Der führende Punkt hält ihn in Unix-Verzeichnislistungen versteckt, und die meisten .gitignore-Vorlagen schließen ihn bereits aus.

Was venv erstellt

.venv/
├── bin/                    # Aktivierungsskripte und ausführbare Dateien (Linux/macOS)
│   ├── activate            # Bash-Aktivierungsskript
│   ├── activate.csh        # C-Shell-Aktivierung
│   ├── activate.fish       # Fish-Shell-Aktivierung
│   ├── pip                 # Isoliertes pip
│   ├── pip3                # Symlink zu pip
│   └── python3             # Symlink zum Python-Interpreter
├── include/                # C-Header für das Erstellen von Erweiterungen
├── lib/python3.x/
│   └── site-packages/      # Wo pip Pakete installiert
└── pyvenv.cfg              # Umgebungskonfiguration

Unter Windows ist die Struktur ähnlich, verwendet aber Scripts/ statt bin/ und .exe-Erweiterungen.

Die Umgebung aktivieren

Die Aktivierung ändert den PATH der Shell, sodass python und pip auf die Kopien der virtuellen Umgebung zeigen statt auf die systemweiten.

# Linux / macOS (Bash/Zsh)
source .venv/bin/activate

# Linux (Fish shell)
source .venv/bin/activate.fish

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Nach der Aktivierung zeigt der Prompt den Umgebungsnamen:

(.venv) user@hostname:~/myproject$

Überprüfen, ob die Umgebung aktiv ist:

# Prüfen, welches Python verwendet wird
which python3
# Ausgabe: /home/user/myproject/.venv/bin/python3

# Prüfen, welches pip verwendet wird
which pip
# Ausgabe: /home/user/myproject/.venv/bin/pip

# Das System-Python bleibt unberührt
python3 -c "import sys; print(sys.prefix)"
# Ausgabe: /home/user/myproject/.venv

Die Umgebung deaktivieren

deactivate

Das stellt den PATH in seinen vorherigen Zustand zurück. Die virtuelle Umgebung bleibt auf der Festplatte — das Deaktivieren löscht nichts.

Pakete mit pip verwalten

Mit aktivierter virtueller Umgebung installiert pip Pakete ausschließlich in diese Umgebung.

Pakete installieren

# Ein bestimmtes Paket installieren
pip install requests

# Eine bestimmte Version installieren
pip install requests==2.31.0

# Mit Versionseinschränkung installieren
pip install "requests>=2.28,<3.0"

# Mehrere Pakete installieren
pip install flask sqlalchemy redis

# Ein Paket aktualisieren
pip install --upgrade requests

# Aus einem Git-Repository installieren
pip install git+https://github.com/user/repo.git@main

Pakete auflisten und prüfen

# Alle installierten Pakete auflisten
pip list

# Detaillierte Informationen zu einem Paket anzeigen
pip show requests

# Auf veraltete Pakete prüfen
pip list --outdated

# Abhängigkeitsbaum anzeigen (pipdeptree zuerst installieren)
pip install pipdeptree
pipdeptree

Pakete deinstallieren

# Ein einzelnes Paket entfernen
pip uninstall requests

# Ein Paket ohne Bestätigungsabfrage entfernen
pip uninstall -y requests

Mit requirements.txt arbeiten

requirements.txt ist der Standardweg, um Python-Projektabhängigkeiten zu deklarieren und zu teilen. Sie listet Pakete und Versionen auf, sodass jeder dieselbe Umgebung nachbauen kann.

requirements.txt erstellen

# Alle installierten Pakete mit exakten Versionen exportieren
pip freeze > requirements.txt

Die Ausgabe sieht so aus:

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

Aus requirements.txt installieren

# Neue Umgebung erstellen und Abhängigkeiten installieren
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Best Practices für requirements.txt

# Exakte Versionen für Produktion fixieren (reproduzierbare Builds)
requests==2.31.0
flask==3.0.2

# >= für Bibliotheksentwicklung verwenden (kompatible Updates erlauben)
requests>=2.28

# Entwicklungsabhängigkeiten in eine zweite Datei auslagern
# requirements-dev.txt:
-r requirements.txt
pytest==8.0.0
black==24.2.0
mypy==1.8.0
# Entwicklungsabhängigkeiten installieren (schließt Produktionsabhängigkeiten ein)
pip install -r requirements-dev.txt

Praxisbeispiel: Auflösung von Abhängigkeitskonflikten

Man tritt einem Team bei, das an einer Webanwendung arbeitet. Nach dem Klonen des Repos erstellt man eine virtuelle Umgebung und führt pip install -r requirements.txt aus. Es schlägt mit einem Versionskonflikt fehl:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
Package A 2.0 requires LibX>=3.0, but you have LibX 2.5 which is incompatible.

So behebt man das:

# Sehen, was das konfliktverursachende Paket benötigt
pip install pipdeptree
pipdeptree --reverse --packages LibX

# Option 1: Das konfliktverursachende Paket aktualisieren
pip install --upgrade LibX

# Option 2: Kompatible Versionen finden
pip install "PackageA>=2.0" "PackageB>=1.0" --dry-run

# requirements.txt mit den aufgelösten Versionen neu erstellen
pip freeze > requirements.txt

Python-Umgebungswerkzeuge im Vergleich

FunktionvenvvirtualenvcondaPoetry
In Python integriertJa (3.3+)Nein (pip install)Nein (separater Installer)Nein (pip install)
GeschwindigkeitMittelSchnellLangsamMittel
Python-VersionsverwaltungNeinNeinJaNein (pyenv verwenden)
Nicht-Python-AbhängigkeitenNeinNeinJa (C-Libs, R, etc.)Nein
Lock-File-UnterstützungNeinNeinenvironment.ymlpoetry.lock
Abhängigkeitsauflösungpip (einfach)pip (einfach)conda solverErweitert
Speicherplatz pro Umgebung~20 MB~20 MB~500 MB+~20 MB
Am besten fürStandard-Python-ProjekteLegacy Python-2-UnterstützungData Science, ML, sprachübergreifendModerne Python-Pakete mit strikten Abhängigkeiten

venv verwenden für Standard-Python-Projekte — es ist das offizielle Werkzeug, benötigt nichts Zusätzliches und funktioniert überall, wo Python läuft. conda verwenden, wenn Nicht-Python-Abhängigkeiten benötigt werden (NumPy mit BLAS, CUDA, R-Pakete). Poetry verwenden, wenn strikte Abhängigkeitsauflösung und ein moderner Workflow für die Paketveröffentlichung benötigt wird.

Virtuelle Umgebungen in CI/CD und Docker

CI/CD-Pipelines (GitHub-Actions-Beispiel)

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          pip install -r requirements.txt
          pip install -r requirements-dev.txt
      - name: Run tests
        run: |
          source .venv/bin/activate
          pytest

Docker (Multi-Stage-Build)

# Build-Stage
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt

# Produktions-Stage
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY . .
CMD ["python", "app.py"]

Die Verwendung einer virtuellen Umgebung innerhalb von Docker ist diskutierbar — der Container bietet bereits Isolation. Multi-Stage-Builds mit venv erzeugen jedoch kleinere Images, weil die Build-Tools und der pip-Cache in der Builder-Stage verbleiben.

Fallstricke und Sonderfälle

Python-Versionskonflikt: Eine virtuelle Umgebung ist an die Python-Version gebunden, die sie erstellt hat. Beim Upgrade von Python 3.11 auf 3.12 können bestehende Umgebungen kaputtgehen. Nach größeren Python-Upgrades sollten sie neu erstellt werden.

--system-site-packages-Lecks: Eine Umgebung mit python3 -m venv --system-site-packages .venv erstellen gibt Zugriff auf global installierte Pakete. Das ist nützlich für schwer per pip installierbare Pakete (wie systemseitig bereitgestelltes PyGObject), bedeutet aber, dass pip freeze Systempakete einschließt und die requirements.txt verunreinigt. pip freeze --local verwenden, um nur umgebungsspezifische Pakete aufzulisten.

pip-Cache füllt die Festplatte: pip speichert heruntergeladene Pakete in ~/.cache/pip/. Auf Build-Servern wächst das unbegrenzt. pip install --no-cache-dir verwenden oder regelmäßig pip cache purge ausführen.

Aktivierung ist Shell-spezifisch: Wenn source .venv/bin/activate in einem Skript verwendet wird, das in einer Subshell läuft, bleibt die Aktivierung nicht erhalten. Stattdessen die Python-Binärdatei direkt aufrufen: .venv/bin/python script.py oder .venv/bin/pip install package.

Windows-PowerShell-Ausführungsrichtlinie: Standardmäßig blockiert PowerShell das Ausführen von Skripten einschließlich der Aktivierung. Einmalig pro Benutzer beheben:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Gemeinsame Netzwerklaufwerke und virtuelle Umgebungen: Virtuelle Umgebungen verwenden Symlinks zum Python-Interpreter. Einige Netzwerkdateisysteme (SMB, NFS) unterstützen keine Symlinks, wodurch die Umgebung fehlschlägt. Umgebungen ausschließlich auf lokalen Datenträgern erstellen.

Fehlerbehebung

”No module named venv"

# Debian/Ubuntu — das venv-Modul installieren
sudo apt install python3-venv

# Manche Distributionen liefern Python ohne venv aus
# Verfügbarkeit prüfen:
python3 -m venv --help

"pip install” schlägt mit Berechtigungsfehlern fehl

# Bei "Permission denied" — wahrscheinlich wurde vergessen, die Umgebung zu aktivieren
source .venv/bin/activate
pip install requests

# NIEMALS sudo pip install verwenden — es verändert Systempakete
# Systemweite Pakete besser über apt/dnf installieren

Umgebung verwendet falsche Python-Version

# Python-Version beim Erstellen der Umgebung angeben
python3.12 -m venv .venv

# Oder den vollständigen Pfad verwenden
/usr/bin/python3.12 -m venv .venv

# Version innerhalb der Umgebung überprüfen
source .venv/bin/activate
python --version

Pakete werden global statt in der Umgebung installiert

# Prüfen, ob pip zur Umgebung gehört
which pip
# Sollte zeigen: .venv/bin/pip

# Wenn /usr/bin/pip angezeigt wird — die Umgebung ist nicht aktiviert
source .venv/bin/activate

Zusammenfassung

  • python3 -m venv .venv erstellt eine isolierte Python-Umgebung — jedes Projekt erhält eigene Pakete, ohne andere Projekte oder das System-Python zu beeinflussen
  • Mit source .venv/bin/activate aktivieren, damit Python und pip der Umgebung die Standardwerkzeuge in der aktuellen Shell-Sitzung werden
  • pip freeze > requirements.txt erfasst exakte Abhängigkeitsversionen — diese Datei in der Versionskontrolle teilen, damit andere die identische Umgebung nachbauen können
  • pip install -r requirements.txt in einer frischen Umgebung reproduziert den Abhängigkeitssatz — für Produktionsdeployments immer Versionen mit == fixieren
  • Niemals sudo pip install verwenden — es verändert Systempakete und erzeugt Konflikte. Virtuelle Umgebungen machen Root-Zugriff vollständig überflüssig
  • Umgebungen nach Python-Upgrades neu erstellen — sie sind an die Python-Version gebunden, die sie erstellt hat, und können bei größeren Versionsänderungen kaputtgehen

Verwandte Artikel