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.lockhä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 --versionInstallation mit pipx
Wenn du lieber pipx verwendest (das CLI-Tools ebenfalls isoliert):
pipx install poetryPoetry aktualisieren
poetry self updateUpdate auf eine bestimmte Version:
poetry self update 1.8.0Tab-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.fishEin 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-projectDas erzeugt folgende Struktur:
my-project/
├── pyproject.toml
├── README.md
├── my_project/
│ └── __init__.py
└── tests/
└── __init__.pyFür ein flaches Source-Layout (Package im Root-Verzeichnis):
poetry new --src my-projectDas legt das Package in ein src/-Verzeichnis:
my-project/
├── pyproject.toml
├── README.md
├── src/
│ └── my_project/
│ └── __init__.py
└── tests/
└── __init__.pyInitialisierung in einem bestehenden Projekt
Wechsle in dein bestehendes Projektverzeichnis und führe aus:
cd existing-project
poetry initPoetry 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-interactionpyproject.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:
| Constraint | Bedeutung | Erlaubt |
|---|---|---|
^2.0 | Kompatible Release | >=2.0.0, <3.0.0 |
^2.1.3 | Kompatible Release (Patch) | >=2.1.3, <3.0.0 |
~2.1 | Ungefähr | >=2.1.0, <2.2.0 |
>=2.0,<3.0 | Range | Explizite Grenzen |
2.1.3 | Exakt | Nur 2.1.3 |
>=2.0 | Minimum | 2.0 und höher |
* | Beliebig | Alle 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 pandasMit Versions-Constraint hinzufügen:
poetry add "pandas>=2.0,<3.0"Zur Development-Gruppe hinzufügen:
poetry add --group dev pytest black ruffZu einer Custom Group hinzufügen:
poetry add --group docs sphinxEin Package aus einem Git-Repository hinzufügen:
poetry add git+https://github.com/user/repo.gitEin 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.0Eine lokale Path-Dependency hinzufügen:
poetry add ../my-local-packageExtras für ein Package hinzufügen:
poetry add "uvicorn[standard]"Packages entfernen
Ein Package entfernen:
poetry remove pandasAus einer bestimmten Gruppe entfernen:
poetry remove --group dev blackInstallierte Packages auflisten
Alle installierten Packages anzeigen:
poetry showDetails zu einem bestimmten Package anzeigen:
poetry show pandasDen Dependency-Tree anzeigen:
poetry show --treeVeraltete Packages anzeigen:
poetry show --outdatedDas 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 installDas 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 lockLockfile-Integrität prüfen:
poetry lock --checkDas 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 trueDas 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 shellDas startet eine neue Shell mit aktivierter virtueller Umgebung. Beenden mit exit oder Ctrl+D.
Umgebungsinformationen
Umgebungsdetails anzeigen:
poetry env infoAlle dem Projekt zugeordneten Umgebungen auflisten:
poetry env listEine bestimmte Python-Version verwenden:
poetry env use python3.11Eine Umgebung entfernen:
poetry env remove python3.11Dependencies installieren
Standardinstallation
Alle Dependencies installieren (main und dev):
poetry installProduktionsinstallation
Ohne Development-Dependencies installieren:
poetry install --without devOhne bestimmte Gruppen installieren:
poetry install --without dev,docsNur bestimmte Gruppen installieren
poetry install --only main
poetry install --only devUmgebung synchronisieren
Packages entfernen, die nicht im Lockfile stehen (Clean Install):
poetry install --syncDas 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 buildDas 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.whlAuf PyPI veröffentlichen
Zuerst deine PyPI-Credentials konfigurieren:
poetry config pypi-token.pypi your-api-tokenDann veröffentlichen:
poetry publish --buildDas 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 passwordDorthin veröffentlichen:
poetry publish --repository privateVersionsmanagement
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.1a0Aktuelle Version anzeigen:
poetry versionMigration 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-interactionSchritt 2: Dependencies aus requirements.txt hinzufügen
Für eine einfache Requirements-Datei:
cat requirements.txt | xargs poetry addFü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 devSchritt 4: Verifizieren und locken
poetry install
poetry lock --checkSchritt 5: Aufräumen
Wenn alles funktioniert, kannst du die alten Dateien entfernen:
rm requirements.txt requirements-dev.txt setup.py setup.cfgZurü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.txtDevelopment-Dependencies einschließen:
poetry export -f requirements.txt --with dev --output requirements-dev.txtPoetry vs pip vs pipenv vs uv: Vergleich
Welches Dependency-Management-Tool passt, hängt von deinen Projektanforderungen ab. Hier ist ein detaillierter Vergleich:
| Feature | Poetry | pip | pipenv | uv |
|---|---|---|---|---|
| Dependency resolution | Advanced SAT solver | Basic (backtracking since 2020) | Moderate | Advanced, Rust-based |
| Lock file | Yes (poetry.lock) | No (manual pip freeze) | Yes (Pipfile.lock) | Yes (uv.lock) |
| Virtual env management | Automatic | Manual (python -m venv) | Automatic | Automatic |
| Build and publish | Built-in | Requires setuptools/twine | No | Built-in |
| Config file | pyproject.toml | requirements.txt | Pipfile | pyproject.toml |
| Speed | Moderate | Fast (no resolution) | Slow | Very fast (Rust) |
| Python version management | No (use pyenv) | No | No | Yes (built-in) |
| Monorepo support | Limited | N/A | No | Yes |
| Script runners | poetry run | No | pipenv run | uv run |
| Maturity | Established (2018) | Standard library adjacent | Established (2017) | Newer (2024) |
| PEP compliance | PEP 518, 621 | N/A | Proprietary format | PEP 518, 621 |
| Community | Large | Massive | Moderate | Growing fast |
| Best for | Full-lifecycle packaging | Simple scripts, legacy | Web applications | Speed-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 --listPoetry 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 installzweimal 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 ipykernelDie Poetry-Umgebung als Jupyter-Kernel registrieren:
poetry run python -m ipykernel install --user --name=my-projectJupyter aus der Poetry-Umgebung heraus starten:
poetry run jupyter notebookFü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
| Command | Beschreibung |
|---|---|
poetry new <name> | Neues Projekt erstellen |
poetry init | In bestehendem Verzeichnis initialisieren |
poetry add <pkg> | Dependency hinzufügen |
poetry remove <pkg> | Dependency entfernen |
poetry install | Alle Dependencies installieren |
poetry update | Dependencies aktualisieren |
poetry lock | Nur das Lockfile aktualisieren |
poetry show | Installierte Packages auflisten |
poetry show --tree | Dependency-Tree anzeigen |
poetry show --outdated | Veraltete Packages anzeigen |
poetry build | Package bauen |
poetry publish | Auf PyPI veröffentlichen |
poetry run <cmd> | Command im Virtualenv ausführen |
poetry shell | Virtualenv-Shell aktivieren |
poetry env info | Umgebungsdetails anzeigen |
poetry version <rule> | Projektversion erhöhen |
poetry export | Nach requirements.txt exportieren |
poetry config --list | Gesamte Konfiguration anzeigen |
poetry search <pkg> | Nach Packages suchen |
poetry check | pyproject.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 -vvvVirtuelle 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 rootDanach .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-updateDas 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.