Python venv: Umgebungen erstellen, aktivieren und im Betrieb verwalten

EdwardMoon

Python venv trennt die Installationsbereiche für Python-Pakete nach Projekten. Die Funktion gehört zur Python-Standardbibliothek. Direkt im System-Python installierte Pakete können Versionskonflikte mit Betriebssystemwerkzeugen oder anderen Anwendungen verursachen. Eine virtuelle Umgebung ermöglicht jedem Projekt, seine benötigten Paketversionen unabhängig zu verwalten.

Dieser Praxisleitfaden behandelt die Erstellung und Prüfung virtueller Umgebungen unter Linux, macOS und Windows sowie requirements.txt, Offline-Wheelhouses, systemd-Dienste, sichere Entfernung und Fehlerdiagnose. Vor dem Übernehmen der Befehle Python-Version und Projektpfade an die tatsächliche Umgebung anpassen.

Schnellstart mit Python venv

Am einfachsten ist eine .venv im Projektverzeichnis, deren Python-Interpreter auch pip ausführt. Gegenüber dem alleinigen Aufruf von pip macht python -m pip eindeutig, dass pip zum aktuell ausgewählten Interpreter gehört.

mkdir -p ~/projects/sample-app
cd ~/projects/sample-app

python3 --version
python3 -m venv .venv
source .venv/bin/activate

python -m pip --version
python -m pip install --upgrade pip
python -m pip install requests
python -c "import requests; print(requests.__version__)"

deactivate

Was Python venv ist und was es isoliert

Ein eigener Ausführungskontext, keine vollständige Python-Kopie

Beim Erstellen entstehen im Zielverzeichnis eine pyvenv.cfg, ein Verzeichnis für ausführbare Dateien und eigene site-packages. Je nach Plattform und Optionen ist die ausführbare Python-Datei eine Kopie oder ein symbolischer Link. venv isoliert daher kein Betriebssystem wie ein Container, sondern hängt vom verwendeten Basis-Python und den Betriebssystembibliotheken ab.

python3 -m venv .venv

find .venv -maxdepth 2 -type f -o -type l | sort | head -30
cat .venv/pyvenv.cfg

Zuverlässig prüfen, ob Python in einer virtuellen Umgebung läuft

Das Aktivierungsskript stellt das Verzeichnis der ausführbaren Dateien an den Anfang von PATH. Da eine Aktivierung jedoch nicht erforderlich ist, reicht die Variable VIRTUAL_ENV allein nicht für eine zuverlässige Erkennung aus. Innerhalb von Python ist der Vergleich von sys.prefix mit sys.base_prefix genauer.

python - <<'PY'
import sys

print("executable   :", sys.executable)
print("prefix       :", sys.prefix)
print("base_prefix  :", sys.base_prefix)
print("inside venv  :", sys.prefix != sys.base_prefix)
PY

Prüfungen vor dem Erstellen einer Python-venv

Zunächst Pfad und Version des gewünschten Python-Interpreters sowie die Verfügbarkeit des venv-Moduls und der pip-Initialisierung prüfen. Bei mehreren Python-Versionen auf demselben Server den Interpreter ausdrücklich angeben, beispielsweise python3.11.

command -v python3
python3 --version
python3 -m venv --help >/dev/null
python3 -m ensurepip --version

Einige Linux-Distributionen liefern venv oder pip als separate Pakete aus. Die Paketnamen hängen von Distribution und Python-Version ab; deshalb zuerst das Repository prüfen. Für das System-Python ist es sicherer, auf sudo pip install zu verzichten.

# Typisches Beispiel für Debian/Ubuntu
sudo apt update
sudo apt install python3-venv python3-pip

# Unter RHEL/Rocky zunächst die verfügbaren Pakete prüfen
sudo dnf list --available 'python3*' | grep -E 'pip|virtualenv'

Erstellung und Aktivierung nach Betriebssystem und Shell

Nach der Aktivierung Pfad und Version kontrollieren. Die Anzeige (.venv) im Prompt dient lediglich als Orientierung. Die zusätzliche Prüfung des tatsächlichen Interpreterpfads hilft, Installationen in der falschen Umgebung zu vermeiden.

command -v python
python --version
python -m pip --version
python -c "import sys; print(sys.executable)"

Python venv ohne Aktivierung ausführen

Für Python venv muss source nicht zwingend ausgeführt werden. In cron, systemd und CI-Jobs ist der direkte Aufruf des absoluten Python-Pfads innerhalb der Umgebung meist besser vorhersehbar und erleichtert die Logauswertung.

# Linux/macOS
/opt/sample-app/.venv/bin/python /opt/sample-app/app.py
/opt/sample-app/.venv/bin/python -m pip list

# Windows PowerShell
.\.venv\Scripts\python.exe .\app.py

Pakete installieren und requirements.txt verwalten

pip immer über den verwendeten Python-Interpreter aufrufen

python -m pip install --upgrade pip
python -m pip install 'requests>=2.32,<3'
python -m pip list
python -m pip check

pip check prüft die Kompatibilität der deklarierten Abhängigkeiten installierter Pakete. Zusammen mit Anwendungstests nach einer Installation hilft es, fehlende oder widersprüchliche Abhängigkeiten früh zu erkennen.

Installationsstand erfassen und wiederherstellen

pip freeze gibt die Versionen der installierten direkten und indirekten Abhängigkeiten aus und eignet sich damit zur Dokumentation eines Produktionsstands. Bei abweichendem Betriebssystem, anderer CPU oder Python-Version lässt sich dieselbe Datei möglicherweise nicht unverändert installieren. Die Laufzeitbedingungen deshalb ebenfalls festhalten.

python -m pip freeze > requirements.txt
python -m pip check

# In einer neuen Umgebung wiederherstellen
python3 -m venv .venv-new
.venv-new/bin/python -m pip install --upgrade pip
.venv-new/bin/python -m pip install -r requirements.txt
.venv-new/bin/python -m pip check

Welche Dateien ins Projekt gehören

# .gitignore
.venv/
__pycache__/
*.py[cod]
.env

# Versionen und Installationsstand dokumentieren
python --version
python -m pip --version
python -m pip freeze

Python venv in abgeschotteten und Offline-Umgebungen betreiben

Für abgeschottete Umgebungen sollte der Internetserver dasselbe Betriebssystem, dieselbe CPU-Architektur und dieselbe Python-Haupt- und Nebenversion wie der Zielserver verwenden. Wheels können von Plattform und Python-ABI abhängen. Dateien von einem beliebigen anderen Rechner zu kopieren, kann daher zu Installationsfehlern führen.

Wheelhouse auf dem Online-Server vorbereiten

python3 -m venv bundle-venv
bundle-venv/bin/python -m pip install --upgrade pip

# Werden nur Wheels zugelassen, fallen Pakete mit notwendigem Quellcode-Build vorab auf.
bundle-venv/bin/python -m pip download   --only-binary=:all:   --dest wheelhouse   -r requirements.txt

sha256sum wheelhouse/* > SHA256SUMS
tar -czf python-wheelhouse.tar.gz wheelhouse requirements.txt SHA256SUMS
sha256sum python-wheelhouse.tar.gz > python-wheelhouse.tar.gz.sha256

Auf dem Offline-Server prüfen und installieren

sha256sum -c python-wheelhouse.tar.gz.sha256
tar -xzf python-wheelhouse.tar.gz

sha256sum -c SHA256SUMS

python3 -m venv .venv
.venv/bin/python -m pip install   --no-index   --find-links=wheelhouse   -r requirements.txt
.venv/bin/python -m pip check

Scheitert ein Paket mit --only-binary=:all:, fehlt ein kompatibles Wheel. In diesem Fall auf einem Online-Buildserver mit den erforderlichen Compilern und Entwicklungs-Headern ein Wheel erstellen. Anschließend auf einem Testserver mit denselben Bedingungen eine neue Umgebung anlegen und Installation sowie Ausführung prüfen.

Python venv in einem systemd-Dienst verwenden

systemd ist keine interaktive Shell; source .venv/bin/activate ist deshalb nicht erforderlich. In ExecStart den absoluten Python-Pfad angeben und Geheimnisse getrennt vom Quellcode in einer Datei mit eingeschränkten Zugriffsrechten verwalten.

# /etc/systemd/system/sample-app.service
[Unit]
Description=Sample Python application
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sampleapp
Group=sampleapp
WorkingDirectory=/opt/sample-app
EnvironmentFile=/etc/sample-app/sample-app.env
ExecStart=/opt/sample-app/.venv/bin/python /opt/sample-app/app.py
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemd-analyze verify /etc/systemd/system/sample-app.service
sudo systemctl daemon-reload
sudo systemctl enable --now sample-app.service
sudo systemctl status sample-app.service --no-pager
sudo journalctl -u sample-app.service -n 100 --no-pager

Warum virtuelle Umgebungen neu erstellt statt verschoben werden sollten

Die Shebang-Zeile installierter Skripte kann den absoluten Pfad des Interpreters enthalten. Beim Kopieren des Verzeichnisses an einen anderen Ort oder auf einen anderen Server kann dieser Pfad ungültig werden. Eine venv deshalb nicht als verteilbares Deployment-Artefakt behandeln. Offiziell empfohlen ist, sie am Ziel neu anzulegen und die Pakete anhand der Abhängigkeitsdatei oder eines Wheelhouse erneut zu installieren.

# Laufzeitbedingungen und Abhängigkeiten der bisherigen Umgebung dokumentieren
.venv/bin/python --version
.venv/bin/python -m pip freeze > requirements.txt

# Am neuen Speicherort neu erstellen
python3 -m venv /opt/sample-app/.venv
/opt/sample-app/.venv/bin/python -m pip install -r requirements.txt
/opt/sample-app/.venv/bin/python -m pip check

Python venv sicher entfernen

Zum Entfernen einer virtuellen Umgebung wird ihr Verzeichnis gelöscht. Ein Tippfehler in einer Variablen oder ein leerer Pfad kann jedoch andere Daten gefährden. Vorher den absoluten Pfad und die pyvenv.cfg prüfen und sicherstellen, dass kein laufender Dienst diese Umgebung nutzt.

# Dieser Block läuft in einer Subshell; ein Abbruch beendet die aktuelle Login-Shell nicht.
(
  set -eu
  VENV="$(realpath -e -- .venv)"
  test -d "$VENV" && test -f "$VENV/pyvenv.cfg" || {
    echo '가상환경 디렉터리가 아니므로 중단합니다.' >&2
    exit 1
  }
  case "$VENV" in /|"$HOME"|/opt|/usr|/var)
    echo '삭제할 수 없는 상위 경로입니다.' >&2; exit 1 ;;
  esac
  printf 'delete target: %s\n' "$VENV"
  grep -R --fixed-strings "$VENV" /etc/systemd/system /etc/cron* 2>/dev/null || true
  # Vor der Antwort die obigen Ergebnisse sowie laufende Dienste und Cron-Jobs prüfen.
  read -r -p '이 경로만 삭제하려면 DELETE 입력: ' answer
  if [ "$answer" != DELETE ]; then
    echo '취소했습니다.'
    exit 0
  fi
  rm -rf -- "$VENV"
)

Häufige Probleme und Lösungen

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version
python -m pip list
python -m pip check
python -m site

venv, virtualenv, pipx oder conda auswählen

• venv: geeignet, um Projektumgebungen mit der Python-Standardbibliothek manuell zu verwalten.
• virtualenv: eine Option, wenn zusätzliche Erstellungsoptionen oder weitergehende Python-Kompatibilität benötigt werden.
• pipx: geeignet für Python-CLI-Werkzeuge wie Black oder Ansible Lint, die systemweit aufrufbar sein sollen, aber jeweils in einer eigenen Anwendungsumgebung installiert werden.
• conda: vor allem in wissenschaftlichen und datenorientierten Umgebungen verbreitet, in denen neben Python-Paketen auch native Bibliotheken gemeinsam verwaltet werden müssen.

Für die übliche Trennung von Projektabhängigkeiten auf Servern und Entwicklungsrechnern ist die standardmäßige Python venv ein einfacher Ausgangspunkt. Andere Werkzeuge bieten sich an, sobald konkrete Anforderungen wie die Verteilung von CLI-Werkzeugen oder native Abhängigkeiten hinzukommen.

Checkliste für die Praxis

1. Gewünschte Python-Datei und Version prüfen, dann die virtuelle Umgebung erstellen.
2. Pakete mit python -m pip installieren und mit pip check prüfen.
3. .venv/ von der Versionsverwaltung ausschließen und requirements- oder Lock-Dateien aufbewahren.
4. Produktionsdienste über den absoluten Pfad des Python-Interpreters der Umgebung starten.
5. Virtuelle Umgebungen am Ziel neu erstellen, statt sie zu kopieren oder zu verschieben.
6. Offline-Bundles unter identischen Betriebssystem-, CPU- und Python-Bedingungen erstellen und SHA-256 prüfen.
7. Vor dem Löschen tatsächlichen Pfad, pyvenv.cfg sowie Verweise in Diensten und cron prüfen.

Weiterführende Anleitungen

• NetBox-Podman-Bundle für abgeschottete Umgebungen erstellen
• Ansible: Grundlagen und Praxisbeispiele

Offizielle Dokumentation

• Offizielle Python-venv-Dokumentation
• PyPA: Pakete mit pip und venv installieren
• pip: reproduzierbare Installationen
• PyPA: eigenständige CLI-Werkzeuge mit pipx installieren

Zusammenfassung

Bei Python venv geht es vor allem darum, Interpreter und Paketpfade eines Projekts zu trennen und die Umgebung reproduzierbar zu verwalten. Während der Entwicklung lässt sich .venv bequem aktivieren; in der Betriebsautomatisierung werden absolute Pfade verwendet. Zusammen mit Abhängigkeitsdateien, dokumentierten Laufzeitbedingungen, Integritätsprüfungen und einem geregelten Austauschverfahren ermöglicht dies einen verlässlichen Betrieb auf Servern und in abgeschotteten Netzen.