RootForge

Python Entwicklungsumgebung unter Linux einrichten – pyenv, venv und pip

Python-Entwicklungsumgebung unter Linux Schritt für Schritt einrichten: pyenv für Versionsverwaltung, virtuelle Umgebungen mit venv, pip-Best-Practices und Projektstruktur.

6 min Lesezeit
  1. Das Problem mit System-Python
  2. pyenv installieren und einrichten
  3. Build-Abhängigkeiten installieren
  4. pyenv installieren
  5. Shell konfigurieren
  6. Python-Versionen mit pyenv verwalten
  7. Verfügbare Versionen anzeigen
  8. Python installieren
  9. Versionen setzen
  10. .python-version im Projekt
  11. Virtuelle Umgebungen mit venv
  12. venv erstellen und aktivieren
  13. venv deaktivieren
  14. .venv in .gitignore aufnehmen
  15. pip: Pakete installieren und verwalten
  16. Pakete installieren
  17. requirements.txt – Abhängigkeiten dokumentieren
  18. Unterschied: requirements.txt vs. pyproject.toml
  19. pip aktuell halten
  20. Projektstruktur und Best Practices
  21. Empfohlene Projektstruktur
  22. requirements-dev.txt für Entwicklungstools
  23. Automatisches venv mit direnv (Optional)
  24. .env-Datei für Geheimnisse
  25. uv: moderner, schneller Ersatz
  26. Häufige Probleme
  27. python: command not found nach pyenv-Installation
  28. ModuleNotFoundError: No module named 'xyz'
  29. pyenv install schlägt fehl (Build-Fehler)
  30. pip install schlägt fehl: "externally managed environment"
  31. Rollback: pyenv entfernen
  32. Fazit

Python Entwicklungsumgebung unter Linux einrichten – pyenv, venv und pip

Python unter Linux einzurichten klingt einfach – ist es aber nicht, wenn man es richtig macht. Das Problem: Linux-Distributionen liefern Python als Systemkomponente. Installierst du Pakete global mit sudo pip install, riskierst du Systeminstabilitäten oder Versionskonflikte zwischen Projekten.

Die Lösung: pyenv für saubere Python-Versionsverwaltung und venv für isolierte Projekt-Umgebungen.

Das Problem mit System-Python

# System-Python zeigt Ubuntu/Debian-Version
python3 --version
# Python 3.12.3  ← fixe Version, vom Paketmanager kontrolliert

# Pakete hier zu installieren ist gefährlich:
sudo pip install requests    # FALSCH – kann Systemkomponenten beschädigen

Warum das problematisch ist:

  • Unterschiedliche Projekte brauchen unterschiedliche Python-Versionen oder Paketversionen
  • sudo pip kann Systemtools überschreiben, die die Distro benötigt
  • Es gibt keine Trennung zwischen Projekten → "works on my machine"-Probleme

Die richtige Strategie:

System-Python → unangetastet (nie sudo pip!)
pyenv         → mehrere Python-Versionen parallel installieren
venv          → pro Projekt isolierte Umgebung
pip           → nur innerhalb der venv

pyenv installieren und einrichten

pyenv baut Python aus dem Quellcode. Dafür werden Build-Abhängigkeiten benötigt.

Build-Abhängigkeiten installieren

# Ubuntu / Debian
sudo apt update
sudo apt install -y \
  make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl git \
  libncursesw5-dev xz-utils tk-dev libxml2-dev \
  libxmlsec1-dev libffi-dev liblzma-dev

# Fedora
sudo dnf install -y \
  make gcc zlib-devel bzip2-devel readline-devel sqlite-devel \
  openssl-devel xz-devel libffi-devel findutils tk-devel

pyenv installieren

# Automatischer Installer (empfohlen)
curl https://pyenv.run | bash

Der Installer installiert pyenv und nützliche Plugins nach ~/.pyenv.

Shell konfigurieren

Füge folgendes in ~/.bashrc (bash) oder ~/.zshrc (zsh) ein:

# pyenv Shell-Integration
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"    # für zsh: eval "$(pyenv init - zsh)"

Änderungen übernehmen:

source ~/.bashrc
# oder neues Terminal öffnen

# Installation prüfen
pyenv --version
# pyenv 2.5.x

Python-Versionen mit pyenv verwalten

Verfügbare Versionen anzeigen

# Alle verfügbaren Python-Versionen
pyenv install --list

# Nur CPython 3.x Versionen filtern
pyenv install --list | grep "^\s*3\."

# Aktuelle stabile Versionen (2026):
# 3.12.x – Stable, LTS
# 3.13.x – Neueste (released Oktober 2024)
# 3.11.x – Ältere LTS, noch verbreitet

Python installieren

# Aktuelle stabile Version (z.B. 3.13.2)
pyenv install 3.13.2

# Ältere Version für Legacy-Projekte
pyenv install 3.11.9

# Fortschritt: dauert einige Minuten (Kompilierung aus Quellcode)

Versionen setzen

# Systemweit (für alle neuen Terminals)
pyenv global 3.13.2

# Nur für aktuelles Verzeichnis (.python-version Datei wird erstellt)
pyenv local 3.12.8

# Nur für aktuelle Shell-Session
pyenv shell 3.11.9

# Aktive Version prüfen
python --version
pyenv version
# 3.13.2 (set by /home/andre/.pyenv/version)

# Alle installierten Versionen
pyenv versions
#   system
# * 3.13.2 (set by /home/andre/.pyenv/version)
#   3.12.8
#   3.11.9

.python-version im Projekt

cd mein-projekt
pyenv local 3.12.8
cat .python-version
# 3.12.8

# Diese Datei ins Repository committen!
# Jeder Mitentwickler bekommt automatisch die richtige Version

Virtuelle Umgebungen mit venv

Auch mit der richtigen Python-Version solltest du pro Projekt eine virtuelle Umgebung anlegen. Sie isoliert alle installierten Pakete.

venv erstellen und aktivieren

# Im Projektverzeichnis
cd mein-projekt

# Virtuelle Umgebung erstellen
python -m venv .venv

# Aktivieren
source .venv/bin/activate

# Prompt ändert sich:
# (.venv) andre@laptop:~/mein-projekt$

# Python-Pfad prüfen (muss auf .venv zeigen)
which python
# /home/andre/mein-projekt/.venv/bin/python

python --version
# Python 3.12.8

venv deaktivieren

deactivate

.venv in .gitignore aufnehmen

echo ".venv/" >> .gitignore

Wichtig: Virtuelle Umgebungen werden nicht ins Repository committet. Stattdessen dokumentierst du die Abhängigkeiten in requirements.txt.

pip: Pakete installieren und verwalten

Immer innerhalb der aktivierten venv arbeiten!

Pakete installieren

# Aktivierte venv prüfen
which pip
# /home/andre/mein-projekt/.venv/bin/pip

# Paket installieren
pip install requests

# Spezifische Version
pip install requests==2.31.0

# Mindestversion
pip install "requests>=2.28.0"

# Paket aktualisieren
pip install --upgrade requests

# Paket deinstallieren
pip uninstall requests

requirements.txt – Abhängigkeiten dokumentieren

# Alle installierten Pakete in Datei schreiben
pip freeze > requirements.txt

cat requirements.txt
# certifi==2024.2.2
# charset-normalizer==3.3.2
# idna==3.6
# requests==2.31.0
# urllib3==2.2.1

# Aus requirements.txt installieren (für neue Entwickler/Server)
pip install -r requirements.txt

Unterschied: requirements.txt vs. pyproject.toml

requirements.txt  → einfach, weit verbreitet, pinned Versionen
pyproject.toml    → moderner Standard (PEP 517/518), für Packages und Tools

Für einfache Projekte reicht requirements.txt. Für Bibliotheken/Packages: pyproject.toml.

pip aktuell halten

# pip selbst aktualisieren
pip install --upgrade pip

Projektstruktur und Best Practices

Empfohlene Projektstruktur

mein-projekt/
├── .python-version       ← pyenv-Versionsdatei
├── .gitignore
├── README.md
├── requirements.txt      ← Abhängigkeiten (für Anwendungen)
├── requirements-dev.txt  ← Entwicklungs-Abhängigkeiten
├── src/
│   └── mein_paket/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

requirements-dev.txt für Entwicklungstools

# Entwicklungstools separat halten
pip install pytest black ruff mypy
pip freeze > requirements-dev.txt

# Produktions-Abhängigkeiten
pip install requests fastapi
pip freeze > requirements.txt

Automatisches venv mit direnv (Optional)

direnv aktiviert die venv automatisch, wenn du das Verzeichnis betrittst:

sudo apt install direnv

# In ~/.bashrc hinzufügen:
eval "$(direnv hook bash)"

# Im Projekt:
echo "source .venv/bin/activate" > .envrc
direnv allow

.env-Datei für Geheimnisse

# .env (nie committen!)
DATABASE_URL=postgresql://user:pass@localhost/db
SECRET_KEY=dein-geheimer-schluessel
DEBUG=True

# In Python laden
pip install python-dotenv

# In Code:
from dotenv import load_dotenv
import os

load_dotenv()
db_url = os.getenv("DATABASE_URL")

uv: moderner, schneller Ersatz

uv ist ein modernes Tool (geschrieben in Rust), das pyenv + pip + venv in einem Tool vereint – und deutlich schneller ist.

# Installation
curl -LsSf https://astral.sh/uv/install.sh | sh

# Python installieren
uv python install 3.13

# Projekt initialisieren
uv init mein-projekt
cd mein-projekt

# Paket hinzufügen
uv add requests fastapi

# Ausführen (venv wird automatisch verwaltet)
uv run python src/main.py

# Skript mit Abhängigkeiten ausführen
uv run --with requests python script.py

Wann uv statt pyenv+pip?

  • Neue Projekte ohne Legacy-Anforderungen: uv
  • Bestehende Projekte mit requirements.txt: pyenv + pip bleibt einfacher
  • Teams mit gemischten Tools: pyenv ist verbreiteter, besser dokumentiert

Häufige Probleme

python: command not found nach pyenv-Installation

# Shell-Integration prüfen
echo $PYENV_ROOT
# /home/andre/.pyenv

# PATH prüfen
echo $PATH | tr ':' '\n' | grep pyenv

# Falls nicht vorhanden: ~/.bashrc nochmal prüfen und neue Shell öffnen
source ~/.bashrc

ModuleNotFoundError: No module named 'xyz'

# Prüfen ob venv aktiviert ist
which python
# Muss auf .venv zeigen, nicht /usr/bin/python

# venv aktivieren
source .venv/bin/activate
pip install xyz

pyenv install schlägt fehl (Build-Fehler)

# Typischer Fehler: fehlende Build-Abhängigkeiten
# Abhängigkeiten prüfen und nachinstallieren
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev

# Dann erneut versuchen
pyenv install 3.13.2

pip install schlägt fehl: "externally managed environment"

Passiert wenn du versuchst, ohne aktivierte venv zu installieren (PEP 668, Ubuntu 23.04+):

error: externally-managed-environment

# Lösung: venv aktivieren!
source .venv/bin/activate
pip install paket

# NICHT: pip install --break-system-packages (riskant)

Rollback: pyenv entfernen

# pyenv deaktivieren und entfernen
rm -rf ~/.pyenv

# Shell-Konfiguration bereinigen
# ~/.bashrc: die drei pyenv-Zeilen entfernen
nano ~/.bashrc   # PYENV_ROOT, PATH und eval-Zeilen löschen

source ~/.bashrc

Fazit

Eine saubere Python-Entwicklungsumgebung auf Linux sieht so aus:

# Einmalig (pro Rechner)
curl https://pyenv.run | bash           # pyenv installieren
pyenv install 3.13.2                    # Python installieren

# Pro Projekt
cd mein-projekt
pyenv local 3.13.2                      # Python-Version pinnen
python -m venv .venv                    # venv erstellen
source .venv/bin/activate               # venv aktivieren
pip install -r requirements.txt         # Abhängigkeiten installieren

War dieser Artikel hilfreich?

Verwandte Artikel

Entwicklungsumgebung

Git Grundlagen – Versionskontrolle verstehen und effektiv nutzen

Git von Grund auf verstehen: Repository anlegen, Commits erstellen, Branches nutzen und mit Remote-Repos arbeiten. Der komplette Git-Einsteiger-Guide für Entwickler.

Entwicklungsumgebung

Neovim Einsteiger-Guide – Terminal-Editor lernen von Grund auf

Neovim installieren, die wichtigsten Befehle lernen und mit LazyVim eine vollwertige IDE im Terminal aufbauen. Für Einsteiger ohne Vorkenntnisse erklärt.

Entwicklungsumgebung

Node.js unter Linux installieren – nvm, npm und die richtige LTS-Version

Node.js sauber unter Linux installieren mit nvm (Node Version Manager). Mehrere Versionen parallel, LTS vs. Current, npm-Grundlagen und häufige Fallstricke vermeiden.