Skip to content

Python Poetry: Moderner Leitfaden für Dependency-Management und Packaging

Updated on

Python-Dependencies zu verwalten sollte nicht schmerzhaft sein. Und doch hat jede Python-Entwicklerin und jeder Python-Entwickler dieses Szenario erlebt: Du klonst ein Projekt, führst pip install -r requirements.txt aus und siehst zu, wie sich Dependency-Konflikte durch dein Terminal ziehen. Paket A braucht Version 1.x einer Library, Paket B braucht Version 2.x, und pip installiert einfach die Version, die es zuletzt auflöst – und bricht dabei stillschweigend eines von beiden. Danach folgen Stunden an Debugging, nur weil pip keinen sauberen Dependency-Resolver und keinen Lockfile-Mechanismus hat.

In Team-Umgebungen verschärft sich das Problem. Eine Person pinnt exakte Versionen, eine andere nutzt lockere Ranges, und eine dritte vergisst, requirements.txt nach der Installation eines neuen Pakets zu aktualisieren. Deployments schlagen fehl. Tests laufen lokal durch, brechen aber in CI. Die Ursache ist immer dieselbe: Pythons Standard-Tooling behandelt Dependency-Management als Nebensache.

Poetry löst das, indem es ein einziges Tool bereitstellt, das Dependency-Auflösung, Virtual-Environment-Management und Package-Publishing abdeckt. Es nutzt die standardisierte Datei pyproject.toml, erzeugt deterministische Lockfiles und löst Dependency-Konflikte vor der Installation – nicht erst danach. Dieser Leitfaden deckt alles ab, von der Installation bis zum Publishing, mit praxisnahen Beispielen für jeden Workflow.

📚

Was ist Python Poetry?

Poetry ist ein Open-Source-Tool für Dependency-Management und Packaging in Python. Es wurde 2018 von Sebastien Eustace erstellt und adressiert den fragmentierten Zustand des Python-Packagings, indem es mehrere Funktionen in einem konsistenten Tool vereint:

  • Dependency-Auflösung: Poetry analysiert alle Dependencies und deren Sub-Dependencies, um kompatible Versionen zu finden, bevor überhaupt etwas installiert wird.
  • Lockfiles: Eine Datei poetry.lock hält die exakten Versionen aller installierten Pakete fest und garantiert reproduzierbare Builds über verschiedene Maschinen hinweg.
  • Virtual-Environment-Management: Poetry erstellt und verwaltet automatisch isolierte virtuelle Umgebungen pro Projekt.
  • Package-Building und Publishing: Poetry baut Source-Distributions und Wheels und veröffentlicht direkt auf PyPI oder in privaten Repositories.
  • Projekt-Scaffolding: Poetry generiert Projektstrukturen mit einer passenden pyproject.toml-Konfiguration.

Poetry verwendet pyproject.toml als Konfigurationsdatei und folgt dabei den Standards PEP 518 und PEP 621. Damit ersetzt es die Kombination aus setup.py, setup.cfg, requirements.txt und MANIFEST.in, die traditionelle Python-Projekte typischerweise benötigen.

Poetry installieren

Poetry liefert einen eigenen Installer, der Poetry von deinen Projekt-Dependencies isoliert und so Versionskonflikte zwischen Poetry selbst und deinen Projektpaketen verhindert.

Empfohlene Installation (offizieller Installer)

Linux, macOS und Windows (WSL):

curl -sSL https://install.python-poetry.org | python3 -

Windows (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Nach der Installation musst du Poetry zu deinem PATH hinzufügen. Der Installer gibt den exakten Pfad aus – typischerweise $HOME/.local/bin unter Linux/macOS oder %APPDATA%\Python\Scripts unter Windows.

Installation verifizieren:

poetry --version

Installation mit pipx

Wenn du lieber pipx verwendest (das CLI-Tools ebenfalls isoliert):

pipx install poetry

Poetry aktualisieren

poetry self update

Update auf eine bestimmte Version:

poetry self update 1.8.0

Tab-Completion aktivieren

Poetry unterstützt Shell-Completion für Bash, Zsh und Fish:

# Bash
poetry completions bash >> ~/.bash_completion
 
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
 
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

Ein neues Projekt erstellen

Poetry bietet zwei Wege, ein Projekt zu starten: ein neues Projekt von Grund auf erstellen oder Poetry in einem bestehenden Projekt initialisieren.

Neues Projekt von Grund auf

poetry new my-project

Das erzeugt folgende Struktur:

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

Für ein flaches Source-Layout (Package im Root-Verzeichnis):

poetry new --src my-project

Das legt das Package in ein src/-Verzeichnis:

my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── __init__.py

Initialisierung in einem bestehenden Projekt

Wechsle in dein bestehendes Projektverzeichnis und führe aus:

cd existing-project
poetry init

Poetry führt dich interaktiv durch das Setup: Paketname, Version, Beschreibung, Autor, Python-Kompatibilität und Dependencies. Du kannst Enter drücken, um Defaults zu übernehmen, oder optionale Felder überspringen.

Für ein nicht-interaktives Setup:

poetry init --name my-package --description "A useful package" --author "Your Name <you@example.com>" --python "^3.9" --no-interaction

pyproject.toml verstehen

Die Datei pyproject.toml ist die Single Source of Truth für die Konfiguration deines Projekts. Hier ist ein vollständiges Beispiel:

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = "A data processing library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/yourname/my-project"
repository = "https://github.com/yourname/my-project"
keywords = ["data", "processing", "analytics"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries",
]
 
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.31"
pydantic = ">=2.0,<3.0"
 
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.0"
ruff = "^0.3"
 
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
sphinx-rtd-theme = "^2.0"
 
[tool.poetry.scripts]
my-cli = "my_project.cli:main"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Syntax für Versions-Constraints

Poetry verwendet eine klare Syntax für Versions-Constraints:

ConstraintBedeutungErlaubt
^2.0Kompatible Release>=2.0.0, <3.0.0
^2.1.3Kompatible Release (Patch)>=2.1.3, <3.0.0
~2.1Ungefähr>=2.1.0, <2.2.0
>=2.0,<3.0RangeExplizite Grenzen
2.1.3ExaktNur 2.1.3
>=2.0Minimum2.0 und höher
*BeliebigAlle Versionen

Der Caret-Constraint (^) ist am gebräuchlichsten und empfohlen. Er erlaubt Updates, die die linkeste nicht-null Ziffer nicht verändern, und folgt damit den Prinzipien von Semantic Versioning.

Dependency-Gruppen

Poetry organisiert Dependencies in Gruppen und ersetzt damit die Notwendigkeit separater Requirements-Dateien:

  • Haupt-Dependencies ([tool.poetry.dependencies]): Erforderlich, damit das Package funktioniert. Diese werden installiert, wenn jemand dein Package installiert.
  • Development-Dependencies ([tool.poetry.group.dev.dependencies]): Tools für Entwicklung, Tests und Linting. Werden nicht in veröffentlichte Packages aufgenommen.
  • Custom Groups ([tool.poetry.group.docs.dependencies]): Jede zusätzliche Gruppierung, die du brauchst, z. B. Dokumentations-Tools.

Dependencies hinzufügen und entfernen

Packages hinzufügen

Ein Package zu den Haupt-Dependencies hinzufügen:

poetry add pandas

Mit Versions-Constraint hinzufügen:

poetry add "pandas>=2.0,<3.0"

Zur Development-Gruppe hinzufügen:

poetry add --group dev pytest black ruff

Zu einer Custom Group hinzufügen:

poetry add --group docs sphinx

Ein Package aus einem Git-Repository hinzufügen:

poetry add git+https://github.com/user/repo.git

Ein Package aus einem bestimmten Branch oder Tag hinzufügen:

poetry add git+https://github.com/user/repo.git#branch-name
poetry add git+https://github.com/user/repo.git#v1.0.0

Eine lokale Path-Dependency hinzufügen:

poetry add ../my-local-package

Extras für ein Package hinzufügen:

poetry add "uvicorn[standard]"

Packages entfernen

Ein Package entfernen:

poetry remove pandas

Aus einer bestimmten Gruppe entfernen:

poetry remove --group dev black

Installierte Packages auflisten

Alle installierten Packages anzeigen:

poetry show

Details zu einem bestimmten Package anzeigen:

poetry show pandas

Den Dependency-Tree anzeigen:

poetry show --tree

Veraltete Packages anzeigen:

poetry show --outdated

Das Lockfile: poetry.lock

Die Datei poetry.lock ist eines der wichtigsten Features von Poetry. Wenn du poetry install oder poetry add ausführst, löst Poetry alle Dependencies auf und schreibt die exakten Versionen (inklusive aller transitiven Dependencies) in poetry.lock.

Warum Lockfiles wichtig sind

Ohne Lockfile kann pip install -r requirements.txt mit lockeren Versions-Constraints auf unterschiedlichen Maschinen oder zu unterschiedlichen Zeitpunkten zu unterschiedlichen Installationen führen. Ein Lockfile eliminiert diese Zufälligkeit.

Betrachte dieses Szenario:

[tool.poetry.dependencies]
requests = "^2.28"

Das erlaubt jede Version von 2.28.0 bis 2.99.x. Ohne Lockfile könnte dein CI-Server 2.31.0 installieren, während deine lokale Maschine 2.28.2 nutzt. Das Lockfile pinnt die exakte Version über alle Umgebungen hinweg.

Lockfile-Workflow

Committe poetry.lock in die Versionsverwaltung. So stellst du sicher, dass jede Entwicklerin/jeder Entwickler und jedes Deployment identische Package-Versionen nutzt.

git add poetry.lock pyproject.toml
git commit -m "Add project dependencies"

Aus dem Lockfile installieren (für reproduzierbare Installationen):

poetry install

Das installiert exakt die Versionen aus poetry.lock und ignoriert neuere kompatible Versionen.

Lockfile aktualisieren, wenn du neuere Versionen willst:

# Alle Packages aktualisieren
poetry update
 
# Ein bestimmtes Package aktualisieren
poetry update pandas
 
# Lockfile aktualisieren ohne zu installieren
poetry lock

Lockfile-Integrität prüfen:

poetry lock --check

Das bestätigt, dass das Lockfile konsistent mit pyproject.toml ist, ohne etwas zu verändern.

Virtual-Environment-Management

Poetry erstellt und verwaltet automatisch virtuelle Umgebungen für deine Projekte.

Standardverhalten

Wenn du poetry install oder poetry add ausführst, erstellt Poetry eine virtuelle Umgebung, falls noch keine existiert. Standardmäßig werden Umgebungen in einem zentralen Cache-Verzeichnis gespeichert:

  • Linux: ~/.cache/pypoetry/virtualenvs/
  • macOS: ~/Library/Caches/pypoetry/virtualenvs/
  • Windows: C:\Users\<user>\AppData\Local\pypoetry\Cache\virtualenvs\

Virtuelle Umgebungen im Projekt

Viele bevorzugen die virtuelle Umgebung im Projektverzeichnis (ähnlich wie Node.js node_modules). Konfiguriere das global:

poetry config virtualenvs.in-project true

Das erstellt ein .venv-Verzeichnis im Projekt-Root, ist leicht auffindbar und kompatibel mit IDE-Auto-Detection.

Commands in der virtuellen Umgebung ausführen

Einen einzelnen Command ausführen:

poetry run python my_script.py
poetry run pytest
poetry run black .

Eine Shell mit aktivierter Umgebung starten:

poetry shell

Das startet eine neue Shell mit aktivierter virtueller Umgebung. Beenden mit exit oder Ctrl+D.

Umgebungsinformationen

Umgebungsdetails anzeigen:

poetry env info

Alle dem Projekt zugeordneten Umgebungen auflisten:

poetry env list

Eine bestimmte Python-Version verwenden:

poetry env use python3.11

Eine Umgebung entfernen:

poetry env remove python3.11

Dependencies installieren

Standardinstallation

Alle Dependencies installieren (main und dev):

poetry install

Produktionsinstallation

Ohne Development-Dependencies installieren:

poetry install --without dev

Ohne bestimmte Gruppen installieren:

poetry install --without dev,docs

Nur bestimmte Gruppen installieren

poetry install --only main
poetry install --only dev

Umgebung synchronisieren

Packages entfernen, die nicht im Lockfile stehen (Clean Install):

poetry install --sync

Das entfernt alle Packages, die manuell installiert wurden oder nicht mehr im Lockfile stehen, sodass die Umgebung exakt zur Projektkonfiguration passt.

Packages bauen und veröffentlichen

Poetry vereinfacht den gesamten Publishing-Workflow.

Dein Package bauen

poetry build

Das erzeugt sowohl eine Source-Distribution (.tar.gz) als auch ein Wheel (.whl) im Verzeichnis dist/:

dist/
├── my_project-1.0.0.tar.gz
└── my_project-1.0.0-py3-none-any.whl

Auf PyPI veröffentlichen

Zuerst deine PyPI-Credentials konfigurieren:

poetry config pypi-token.pypi your-api-token

Dann veröffentlichen:

poetry publish --build

Das Flag --build baut und veröffentlicht in einem Schritt.

In ein privates Repository veröffentlichen

Ein privates Repository hinzufügen:

poetry config repositories.private https://private.pypi.example.com/simple/
poetry config http-basic.private username password

Dorthin veröffentlichen:

poetry publish --repository private

Versionsmanagement

Versionen nach Semantic Versioning erhöhen:

poetry version patch    # 1.0.0 -> 1.0.1
poetry version minor    # 1.0.0 -> 1.1.0
poetry version major    # 1.0.0 -> 2.0.0
poetry version prepatch # 1.0.0 -> 1.0.1a0

Aktuelle Version anzeigen:

poetry version

Migration von requirements.txt

Wenn du ein bestehendes Projekt mit requirements.txt hast, ist die Migration zu Poetry unkompliziert.

Schritt 1: Poetry initialisieren

cd your-project
poetry init --no-interaction

Schritt 2: Dependencies aus requirements.txt hinzufügen

Für eine einfache Requirements-Datei:

cat requirements.txt | xargs poetry add

Für Dateien mit Versions-Constraints: Packages manuell hinzufügen oder ein Migrationsskript nutzen:

import subprocess
 
with open("requirements.txt") as f:
    packages = []
    for line in f:
        line = line.strip()
        if line and not line.startswith("#") and not line.startswith("-"):
            packages.append(line)
 
if packages:
    subprocess.run(["poetry", "add"] + packages)

Schritt 3: Development-Dependencies hinzufügen

Wenn du eine requirements-dev.txt hast:

cat requirements-dev.txt | xargs poetry add --group dev

Schritt 4: Verifizieren und locken

poetry install
poetry lock --check

Schritt 5: Aufräumen

Wenn alles funktioniert, kannst du die alten Dateien entfernen:

rm requirements.txt requirements-dev.txt setup.py setup.cfg

Zurück nach requirements.txt exportieren

Wenn du aus Kompatibilitätsgründen (Docker-Builds, Legacy-CI-Systeme) eine requirements.txt brauchst:

poetry export -f requirements.txt --output requirements.txt

Development-Dependencies einschließen:

poetry export -f requirements.txt --with dev --output requirements-dev.txt

Poetry vs pip vs pipenv vs uv: Vergleich

Welches Dependency-Management-Tool passt, hängt von deinen Projektanforderungen ab. Hier ist ein detaillierter Vergleich:

FeaturePoetrypippipenvuv
Dependency resolutionAdvanced SAT solverBasic (backtracking since 2020)ModerateAdvanced, Rust-based
Lock fileYes (poetry.lock)No (manual pip freeze)Yes (Pipfile.lock)Yes (uv.lock)
Virtual env managementAutomaticManual (python -m venv)AutomaticAutomatic
Build and publishBuilt-inRequires setuptools/twineNoBuilt-in
Config filepyproject.tomlrequirements.txtPipfilepyproject.toml
SpeedModerateFast (no resolution)SlowVery fast (Rust)
Python version managementNo (use pyenv)NoNoYes (built-in)
Monorepo supportLimitedN/ANoYes
Script runnerspoetry runNopipenv runuv run
MaturityEstablished (2018)Standard library adjacentEstablished (2017)Newer (2024)
PEP compliancePEP 518, 621N/AProprietary formatPEP 518, 621
CommunityLargeMassiveModerateGrowing fast
Best forFull-lifecycle packagingSimple scripts, legacyWeb applicationsSpeed-critical workflows

Wann du welches Tool wählen solltest

Wähle Poetry, wenn du eine vollständige Packaging-Lösung brauchst – Dependency-Management, Build und Publishing nach PyPI in einem Tool, mit ausgereiftem Ökosystem und umfangreicher Dokumentation.

Wähle pip für einfache Skripte, schnelles Prototyping oder wenn du an Einschränkungen gebunden bist, die Standard-Tooling erfordern. Pip bleibt das Fundament, auf dem andere Tools aufbauen.

Wähle pipenv für Webanwendungen, in denen du reproduzierbare Umgebungen brauchst, aber keine Packages auf PyPI veröffentlichst. Das Pipfile-Format trennt Development- und Production-Dependencies klar.

Wähle uv, wenn Installationsgeschwindigkeit Priorität hat oder du ein einzelnes Tool willst, das auch Python-Versionen verwaltet. uv ist in Rust geschrieben und löst Dependencies deutlich schneller als Python-basierte Tools auf. Es ist pip-kompatibel und kann als Drop-in-Replacement dienen.

Poetry-Konfiguration und Tipps

Nützliche Konfigurationsoptionen

# Store virtual environments in the project directory
poetry config virtualenvs.in-project true
 
# Use a specific Python version for new environments
poetry config virtualenvs.prefer-active-python true
 
# Disable automatic virtual environment creation
poetry config virtualenvs.create false
 
# View all configuration
poetry config --list

Poetry mit Docker

Ein Production-Dockerfile mit Poetry:

FROM python:3.12-slim
 
ENV POETRY_VERSION=1.8.0 \
    POETRY_HOME="/opt/poetry" \
    POETRY_VIRTUALENVS_CREATE=false \
    POETRY_NO_INTERACTION=1
 
RUN pip install poetry==$POETRY_VERSION
 
WORKDIR /app
 
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
 
COPY . .
RUN poetry install --without dev
 
CMD ["python", "-m", "my_project"]

Wichtige Punkte:

  • POETRY_VIRTUALENVS_CREATE=false überspringt die Erstellung einer virtuellen Umgebung im Container (der Container selbst sorgt für Isolation).
  • Installiere Dependencies, bevor du den Source Code kopierst, um Docker-Layer-Caching optimal zu nutzen.
  • poetry install zweimal ausführen: zuerst ohne das Projekt (nur Dependencies), dann mit dem Projekt.

Poetry mit CI/CD

GitHub Actions Beispiel:

name: CI
 
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 Poetry
        run: pip install poetry
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest
      - name: Run linting
        run: poetry run ruff check .

Poetry in Jupyter-Workflows

Data Scientists arbeiten häufig in Jupyter-Notebooks, wo Dependency-Management besonders wichtig ist. Poetry integriert sich gut in Jupyter, indem es sicherstellt, dass Notebooks die richtige Umgebung nutzen.

Jupyter innerhalb deines Poetry-Projekts installieren:

poetry add --group dev jupyter ipykernel

Die Poetry-Umgebung als Jupyter-Kernel registrieren:

poetry run python -m ipykernel install --user --name=my-project

Jupyter aus der Poetry-Umgebung heraus starten:

poetry run jupyter notebook

Für ein schlankes Jupyter-Erlebnis mit automatischem Dependency-Management und KI-gestützter Unterstützung bietet RunCell (opens in a new tab) eine integrierte Umgebung, in der du dich auf Analyse statt auf Environment-Konfiguration konzentrieren kannst. RunCell übernimmt Package-Installation und Kernel-Management automatisch – das ergänzt Poetries projektbezogene Dependency-Kontrolle.

Referenz: Häufige Poetry-Commands

CommandBeschreibung
poetry new <name>Neues Projekt erstellen
poetry initIn bestehendem Verzeichnis initialisieren
poetry add <pkg>Dependency hinzufügen
poetry remove <pkg>Dependency entfernen
poetry installAlle Dependencies installieren
poetry updateDependencies aktualisieren
poetry lockNur das Lockfile aktualisieren
poetry showInstallierte Packages auflisten
poetry show --treeDependency-Tree anzeigen
poetry show --outdatedVeraltete Packages anzeigen
poetry buildPackage bauen
poetry publishAuf PyPI veröffentlichen
poetry run <cmd>Command im Virtualenv ausführen
poetry shellVirtualenv-Shell aktivieren
poetry env infoUmgebungsdetails anzeigen
poetry version <rule>Projektversion erhöhen
poetry exportNach requirements.txt exportieren
poetry config --listGesamte Konfiguration anzeigen
poetry search <pkg>Nach Packages suchen
poetry checkpyproject.toml validieren

Troubleshooting häufiger Probleme

Fehler bei der Dependency-Auflösung

Problem: Poetry findet keinen kompatiblen Satz an Versionen.

SolverProblemError: ...unable to find compatible versions...

Lösung: Versions-Constraints lockern oder nach konfliktierenden Anforderungen suchen:

# Show what conflicts exist
poetry show --tree
 
# Try with a wider constraint
poetry add "problematic-package>=1.0"

Langsame Auflösung

Problem: poetry lock dauert sehr lange.

Lösung: Poetry cached Package-Metadaten, aber die erste Auflösung in einem Projekt mit vielen Dependencies kann langsam sein. Wenn die Auflösung mehrere Minuten überschreitet:

# Clear the cache and retry
poetry cache clear --all pypi
 
# Use verbose output to see what is happening
poetry lock -vvv

Virtuelle Umgebung wird von der IDE nicht erkannt

Problem: VS Code oder PyCharm findet die Poetry-Umgebung nicht.

Lösung: In-Project-Virtualenvs konfigurieren:

poetry config virtualenvs.in-project true
poetry install  # Recreates .venv in project root

Danach .venv/bin/python als Interpreter in deiner IDE auswählen.

Hash-Mismatch-Fehler

Problem: poetry install meldet Hash-Mismatches.

Lösung: Lockfile neu generieren:

poetry lock --no-update

Das generiert Hashes neu, ohne Dependency-Versionen zu ändern.

FAQ

Wofür wird Python Poetry verwendet?

Python Poetry ist ein Tool für Dependency-Management und Packaging, das Package-Installation, das Auflösen von Versionskonflikten, das Verwalten virtueller Umgebungen und das Veröffentlichen von Packages auf PyPI übernimmt. Es ersetzt die Kombination aus pip, venv, setuptools und twine durch ein einziges, einheitliches Tool, das auf der Konfiguration in pyproject.toml basiert.

Ist Poetry besser als pip?

Poetry und pip erfüllen unterschiedliche Zwecke. Poetry bietet Dependency-Auflösung, Lockfiles, Virtual-Environment-Management und Package-Publishing in einem Tool. Pip ist einfacher und funktioniert gut für unkomplizierte Installationen. Für Projekte, die reproduzierbare Builds, Team-Zusammenarbeit oder Package-Publishing benötigen, bringt Poetry deutliche Vorteile. Für schnelle Skripte oder kleine Projekte reicht pip weiterhin aus.

Wie wechsle ich von pip zu Poetry?

Initialisiere Poetry in deinem Projekt mit poetry init und füge dann deine Dependencies aus requirements.txt mit cat requirements.txt | xargs poetry add hinzu. Poetry erstellt eine pyproject.toml und eine poetry.lock. Nachdem du mit poetry install verifiziert hast, dass alles funktioniert, kannst du die alte requirements.txt entfernen. Mit poetry export kannst du bei Bedarf weiterhin eine requirements.txt für Kompatibilität erzeugen.

Ersetzt Poetry virtualenv?

Ja. Poetry erstellt und verwaltet automatisch virtuelle Umgebungen für jedes Projekt. Du musst Umgebungen nicht manuell erstellen oder aktivieren. Standardmäßig speichert Poetry Umgebungen in einem zentralen Cache, oder im Projektverzeichnis, wenn du poetry config virtualenvs.in-project true setzt. Mit poetry shell kannst du die Umgebung weiterhin interaktiv aktivieren.

Kann Poetry mehrere Python-Versionen verwalten?

Poetry selbst installiert keine Python-Versionen, arbeitet aber mit den Python-Versionen, die auf deinem System verfügbar sind. Nutze pyenv oder uv, um mehrere Python-Versionen zu installieren, und teile Poetry dann mit poetry env use python3.11 mit, welche verwendet werden soll. Poetry erstellt separate virtuelle Umgebungen für unterschiedliche Python-Versionen innerhalb desselben Projekts.

Was ist der Unterschied zwischen poetry.lock und requirements.txt?

Eine poetry.lock zeichnet jedes installierte Package und dessen exakte Version auf – inklusive aller transitiven Dependencies – sowie Content-Hashes zur Verifikation. Eine per pip freeze erzeugte requirements.txt listet ebenfalls exakte Versionen, hat aber keine Hash-Verifikation und keine Nachverfolgung der Dependency-Beziehungen. Das Lockfile sorgt für deterministische Installationen über alle Umgebungen hinweg, während requirements.txt unterschiedliche Ergebnisse liefern kann, wenn sich transitive Dependencies aktualisieren.

Fazit

Python Poetry verwandelt Dependency-Management von einer Reibungsquelle in einen schlanken Workflow. Indem es Dependency-Auflösung, Virtual-Environment-Management und Package-Publishing in einem Tool kombiniert, beseitigt es die fragmentierte Toolchain, die Python-Entwicklerinnen und -Entwickler lange frustriert hat. Die Datei pyproject.toml dient als Single Source of Truth, das Lockfile garantiert reproduzierbare Installationen, und der Dependency-Resolver erkennt Konflikte, bevor sie Runtime-Fehler verursachen.

Ob du eine Library für PyPI baust, eine komplexe Anwendung mit dutzenden Dependencies verwaltest oder in einem Team arbeitest, das konsistente Umgebungen braucht: Poetry liefert die Struktur und Zuverlässigkeit, die pip allein nicht bieten kann. Die Lernkurve ist moderat – die meisten werden innerhalb einer Stunde produktiv – und die eingesparte Zeit beim Debugging von Dependency-Problemen zahlt sich bereits in der ersten Woche aus.

Starte, indem du bei deinem nächsten Projekt poetry new ausführst oder in einem bestehenden poetry init. Füge deine Dependencies hinzu, committe das Lockfile und erlebe Dependency-Management so, wie es sein sollte. Für Data-Science-Workflows in Jupyter kombiniere Poetries projektbezogene Dependency-Kontrolle mit RunCell (opens in a new tab) für eine Umgebung, die sowohl Package-Management als auch interaktive Analyse nahtlos abdeckt.

📚