Poetry: Python Dependency Management

2.3.2 · active · verified Sat Mar 28

Poetry is a comprehensive tool for Python dependency management and packaging, leveraging `pyproject.toml` for configuration and a `poetry.lock` file for consistent, reproducible environments. It handles dependency resolution, virtual environment management, and project building. The current version is 2.3.2, with frequent minor and patch releases, though without a fixed release cycle.

Warnings

breaking Poetry 2.0 introduced significant breaking changes. Commands like `poetry export` and `poetry shell` are no longer core features and require separate plugins (`poetry-plugin-export` and `poetry-plugin-shell`). `poetry env activate` is the recommended replacement for `poetry shell`. The interface for `poetry add --optional` also changed. The minimum Python version for generated SDKs changed to 3.10.
Fix: Install necessary plugins (`poetry self add poetry-plugin-export`, `poetry self add poetry-plugin-shell`), use `poetry env activate` instead of `poetry shell`, and review `poetry add` usage for optional dependencies. Ensure Python 3.10+ is used for projects requiring it.
breaking Python 3.9 support was dropped in Poetry 2.3.0. Projects requiring 3.9 will need to use an older Poetry version or upgrade their Python environment.
Fix: Upgrade project's Python version to 3.10 or higher, or explicitly use a Poetry version that supports Python 3.9 (e.g., `poetry==2.2.*`).
gotcha PEP 735 dependency groups (introduced in Poetry 2.2.0) had issues with lock file hashing, meaning changes to these groups were not always reflected in `poetry.lock`. This was fixed in Poetry 2.3.0.
Fix: When using PEP 735 dependency groups, ensure you are running Poetry 2.3.0 or later. If using older 2.2.x, manually run `poetry lock` to ensure `poetry.lock` is up-to-date after modifying dependency groups.
gotcha Do NOT install Poetry using `pip install poetry` directly into your project's virtual environment. This can lead to dependency conflicts and unintended upgrades. Poetry should be installed in an isolated environment (e.g., via `pipx` or its official installer).
Fix: Use `pipx install poetry` or the official installer script to install Poetry globally in its own isolated environment. Avoid `pip install poetry` within your project's virtual environment.
gotcha The default behavior of `installer.re-resolve` changed from `true` to `false` in Poetry 2.3.0. This means Poetry now evaluates locked groups and markers to decide on package installation, rather than always re-resolving. While this makes installation clearer and faster, it might expose issues if your lock file or environment setup was previously relying on implicit re-resolution.
Fix: Review your installation workflows. If you encounter unexpected installation behavior, you can revert to the old default by setting `installer.re-resolve = true` in your Poetry configuration.
gotcha The caret (`^`) operator for dependency version constraints can be a 'footgun' if applied indiscriminately, especially to packages that do not strictly follow Semantic Versioning (e.g., CalVer like `tzdata`). This can lead to either overly strict or overly lax dependency pinning, causing issues for users or maintainers.
Fix: Carefully consider the versioning scheme of each dependency. For non-SemVer packages, use more precise constraints (e.g., `~=`, explicit `<` bounds) instead of `^`. Review and manually adjust constraints where necessary.
deprecated In a future minor release, Poetry will change its default behavior for projects without an explicit `[build-system]` section in `pyproject.toml`. It will fall back to `setuptools` instead of the current behavior of warning and defaulting to `poetry-core`.
Fix: Explicitly define your build system in `pyproject.toml` (e.g., `[build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api"`) to ensure consistent behavior across Poetry versions.

Install

pipx install poetry Recommended via pipx (isolated environment)
curl -sSL https://install.python-poetry.org | python3 - Official installer (Linux/macOS)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python - Official installer (Windows PowerShell)

Quickstart

Initialize a new Poetry project, add dependencies, install them into a managed virtual environment, and execute commands within that environment.

# 1. Create a new project
poetry new my-project

# 2. Navigate into the project directory
cd my-project

# 3. Add a dependency
poetry add requests

# 4. Install project dependencies (creates virtual environment if needed)
poetry install

# 5. Run a command within the project's virtual environment
poetry run python -c "import requests; print('Requests is installed!')"

view raw JSON →