Claude Code & Poetry: Python-Projekte professionell verwalten

Wer Python-Projekte mit pip install und handgepflegten requirements.txt-Dateien verwaltet, kennt das Problem: Die Umgebung läuft lokal, auf dem CI-Server fehlt eine transitive Abhängigkeit, und beim nächsten Entwickler stimmen die Versionen nicht. Poetry löst dieses Problem grundlegend — mit einem einzigen Werkzeug für Abhängigkeiten, virtuelle Umgebungen und Packaging.

Dieser Artikel zeigt, wie Poetry funktioniert und wie Claude Code dabei hilft, schneller produktiv zu werden: von der ersten Installation bis zum Publishing auf PyPI.

1. Poetry vs. pip und venv: Was ist der Unterschied?

Das klassische Python-Toolset besteht aus mehreren Einzelwerkzeugen, die man manuell koordinieren muss: venv für virtuelle Umgebungen, pip für Pakete, pip freeze für Snapshots, requirements.txt für Abhängigkeitslisten und setup.py oder setup.cfg für Packaging. Jedes Werkzeug macht seinen Job — aber zusammen ergeben sie keinen robusten Workflow.

Poetry fasst das alles in einem Werkzeug zusammen:

• Abhängigkeiten deklarieren und auflösen — mit vollständiger Versionspinning-Logik
• Virtuelle Umgebungen automatisch verwalten — Poetry erstellt und aktiviert sie selbstständig
• Reproducible Builds — über poetry.lock, der alle transitiven Abhängigkeiten einfriert
• Packaging und Publishing — direkt auf PyPI, ohne setup.py

Der entscheidende Vorteil: poetry install auf einem neuen Rechner installiert exakt dieselbe Umgebung wie auf deinem — nicht "ungefähr dieselbe", sondern bit-für-bit identisch, weil poetry.lock jede Version jeder Abhängigkeit inklusive aller transitiven Pakete einfriert.

2. Ein Projekt starten: pyproject.toml verstehen

Poetry verwendet pyproject.toml als zentrale Konfigurationsdatei — den modernen Standard, der seit PEP 517 und 518 die alte setup.py ablöst. Alle Projektmetadaten, Abhängigkeiten und Build-Einstellungen stehen an einem Ort.

poetry new mein-projekt

Das erzeugt die Projektstruktur inklusive einer vorausgefüllten pyproject.toml. Für ein bestehendes Projekt:

cd bestehendes-projekt
poetry init

Eine typische pyproject.toml sieht so aus:

[tool.poetry]
name = "mein-projekt"
version = "0.1.0"
description = "Ein Beispielprojekt"
authors = ["Daniel Bratschke <daniel@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.31"
pydantic = "^2.5"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
ruff = "^0.1"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Claude Code kann diese Datei lesen, bestehende Projektstrukturen analysieren und erklären, welche Felder für welchen Zweck wichtig sind — besonders hilfreich beim ersten Kontakt mit pyproject.toml oder beim Überführen eines alten setup.py-Projekts.

3. Abhängigkeiten hinzufügen und aktualisieren

Das Hinzufügen von Paketen ist mit Poetry deutlich sicherer als mit pip install: Poetry prüft Versionskonflikte vor der Installation und aktualisiert poetry.lock automatisch.

# Paket zur Hauptabhängigkeit hinzufügen
poetry add fastapi

# Bestimmte Version pinnen
poetry add "sqlalchemy==2.0.23"

# Neueste kompatible Version innerhalb eines Major-Releases
poetry add "httpx^0.25"

Aktualisieren funktioniert ebenso sauber:

# Einzelnes Paket aktualisieren
poetry update requests

# Alle Pakete auf neueste kompatible Versionen
poetry update

4. Gruppen: Abhängigkeiten sauber trennen

Eine der nützlichsten Funktionen von Poetry sind Abhängigkeitsgruppen. Statt einer einzigen requirements.txt für alles trennt man Produktions-, Entwicklungs- und Testabhängigkeiten sauber voneinander.

# Testabhängigkeit zur test-Gruppe hinzufügen
poetry add --group test pytest pytest-cov

# Dokumentationswerkzeuge zur docs-Gruppe
poetry add --group docs mkdocs mkdocs-material

# Nur Produktionsabhängigkeiten installieren (für Deployment)
poetry install --only main

# Alle Gruppen außer docs installieren
poetry install --without docs

Auf dem CI-Server installiert man nur das Nötige: poetry install --with test --without docs. Im Produktions-Docker-Image nur --only main. Die Gruppen machen das explizit und wartbar, ohne mehrere requirements-*.txt-Dateien zu pflegen.

Claude Code versteht diese Struktur direkt. Wenn du fragst "Wie richte ich die CI-Pipeline für dieses Poetry-Projekt ein?", liest Claude Code die pyproject.toml, sieht die Gruppen und schlägt den passenden poetry install-Befehl für die jeweilige Umgebung vor.

5. Virtuelle Umgebungen mit Poetry

Poetry verwaltet virtuelle Umgebungen vollständig automatisch. Beim ersten poetry install oder poetry add wird eine neue Umgebung erstellt und alle weiteren Befehle laufen automatisch darin.

# Infos zur aktuellen Umgebung anzeigen
poetry env info

# Befehl im Kontext der Umgebung ausführen
poetry run python mein_skript.py
poetry run pytest

# Shell mit aktivierter Umgebung öffnen
poetry shell

Standardmäßig legt Poetry Umgebungen in einem zentralen Verzeichnis ab (z. B. ~/.cache/pypoetry/virtualenvs/). Wer Umgebungen lieber im Projektverzeichnis haben möchte — nützlich bei IDE-Integrationen:

poetry config virtualenvs.in-project true

Dann liegt die Umgebung unter .venv/ im Projektordner, und IDEs wie VS Code oder PyCharm erkennen sie automatisch.

6. poetry.lock: Reproducible Builds verstehen

Die poetry.lock-Datei ist der Kern von Poetrys Reproduzierbarkeit. Sie enthält nicht nur die direkten Abhängigkeiten, sondern alle transitiven Abhängigkeiten mit exakten Versionen und Prüfsummen.

"Wenn poetry.lock im Repository liegt und alle Entwickler poetry install verwenden, haben alle exakt dieselbe Umgebung — auch in sechs Monaten noch, wenn neuere Paketversionen erschienen sind."

Wichtige Regeln zum Umgang mit poetry.lock:

• Ins Repository committen — sowohl für Applikationen als auch für Libraries, wenn Reproduzierbarkeit wichtig ist
• Nie manuell editieren — die Datei wird ausschließlich von Poetry selbst verwaltet
• poetry install statt poetry update auf Deployment-Systemen — damit werden exakt die in der Lock-Datei enthaltenen Versionen installiert

7. Auf PyPI veröffentlichen

Poetry macht das Publishing auf PyPI zu einem Zwei-Schritte-Prozess. Zunächst das Paket bauen:

poetry build

Das erzeugt unter dist/ ein Wheel (.whl) und ein Source-Archiv (.tar.gz). Dann veröffentlichen:

poetry publish

Poetry fragt nach dem PyPI-Token, wenn keiner konfiguriert ist. Den API-Token aus dem PyPI-Konto holt man einmalig und konfiguriert ihn sicher:

poetry config pypi-token.pypi <TOKEN>

Für Testveröffentlichungen auf TestPyPI:

poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish --repository testpypi

8. Claude Code-Tipps für Poetry-Projekte

Claude Code und Poetry ergänzen sich gut, weil Claude Code Dateiinhalte direkt liest und Befehle kennt. Ein paar Anwendungsfälle, die in der Praxis besonders nützlich sind:

Migration von pip zu Poetry

claude "Konvertiere diese requirements.txt in eine pyproject.toml für Poetry
und trenne dabei Produktions- und Entwicklungsabhängigkeiten" < requirements.txt

Claude Code liest die bestehende Datei, ordnet Pakete den passenden Gruppen zu und generiert eine vollständige pyproject.toml — inklusive sinnvoller Versionsgrenzen statt harter Pins.

Abhängigkeitskonflikte verstehen

Wenn poetry add mit einem Konflikt abbricht, ist die Fehlermeldung manchmal kryptisch:

poetry add pandas 2>&1 | claude "Erkläre den Versionskonflikt und schlage eine Lösung vor"

pyproject.toml für bestehende Projekte ergänzen

claude "Ergänze die pyproject.toml um eine sinnvolle Ruff-Konfiguration
für dieses Python-Projekt"

Claude Code liest den vorhandenen Code, erkennt den Stil und schlägt eine passende Linter-Konfiguration vor — direkt in [tool.ruff] innerhalb der pyproject.toml, statt eine separate ruff.toml anzulegen.

Zwei verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code für Python-Projekte — der breitere Überblick über Python-Workflows mit Claude Code
• Claude Code Debugging — wie Claude Code Bugs in Python-Projekten systematisch aufspürt