Versions & Release History

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

This page summarises what changed in Poetry between 1.2 (2022) and 2.5.1 (2026-09-20), the release this section is written against, with poetry-core 2.5.0. Dates are those of the Poetry changelog. Each change links to the page that explains it. The upgrade from 1.x to 2.x has its own page: Migrating to Poetry 2. Projects still on 1.x can read the Poetry 1.8 documentation (1.8.5, 2024-12-06, was the last 1.x release).

A timeline of Poetry milestones: 1.2 groups and plugins, 1.5 source priorities, 1.8 package-mode, 2.0 the [project] table, 2.2 PEP 735 groups and PEP 639, 2.3 re-resolve off, 2.4 release-age cooldown, 2.5 built-in uninstaller

How Poetry is released

Version numbers are PEP 440 major.minor.micro, bumped "similar to Python’s versioning", and explicitly not semantic versioning. A major bump (2.0.0) only comes for breaking changes that cannot go through a deprecation cycle; a minor release may add features, add deprecations and drop features deprecated in an earlier minor release; a micro release usually only fixes bugs and never drops a deprecated feature. So read the changelog before every minor upgrade, and pin Poetry in CI. The FAQ’s reason: with so many users, almost any change breaks someone, and bumping the major version every time would make the minor number meaningless.
Two packages. poetry is the command-line tool; poetry-core is the PEP 517 build back end that [build-system] names, with its own version (here 2.5.0). A project’s builds depend only on poetry-core, so building it does not need the Poetry CLI at all.
Python support. Poetry 2.5.1 itself requires Python >=3.10,<4.0 and officially supports 3.15 since 2.5.0. Projects managed by it can target other Pythons; Poetry’s own interpreter is independent of the project’s.
Pre-releases are installed with --preview (installer script, poetry self update --preview) or by pinning a version.

Python versions and Poetry

Change	Poetry release
Python 3.7 dropped	1.6.0 (2023-08-20)
Python 3.12 officially supported	1.7.0 (2023-11-03)
Python 3.13 officially supported	1.8.4 (2024-10-14)
Python 3.8 dropped	2.0.0 (2025-01-05)
Python 3.14 officially supported	2.2.0 (2025-09-14)
Python 3.9 dropped	2.3.0 (2026-01-18)
Python 3.15 officially supported	2.5.0 (2026-09-19)

Source: Poetry FAQ: What kind of versioning scheme does Poetry use for itself?, Why does Poetry not adhere to semantic versioning?, Poetry changelog, Poetry: System requirements.

Release by release

Release What changed Explained on

Release	What changed	Explained on
1.2.0 (2022-08-31)	The standalone installer (`install.python-poetry.org`); dependency groups, including optional ones (`[tool.poetry.group.<name>]`), the plugin system, the `poetry self` commands, `poetry export` moved to `poetry-plugin-export`, Dulwich instead of the `git` command, `install --sync`, `installer.no-binary`, single-page link sources; the old `get-poetry.py` installer deprecated.	Groups, Plugins
1.3.0 (2022-12-09)	Lock file format 2.0.	Lock File
1.4.0 (2023-02-27)	A modern installer independent of pip (`installer.modern-installation`); the old installer deprecated.
1.5.0 (2023-05-19)	Source `priority` with `supplemental` and `explicit`; the `default` and `secondary` flags deprecated; the implicit PyPI’s priority configurable.	Sources
1.6.0 (2023-08-20)	`poetry check --lock` replaces `poetry lock --check`; Python 3.7 dropped.	check
1.7.0 (2023-11-03)	Python 3.12; `poetry version --next-phase`; the `poetry-install` pre-commit hook; a warning that `poetry-plugin-export` will stop being installed by default.
1.8.0 (2024-02-25)	`package-mode = false` for projects that only manage dependencies; PEP 658 metadata and `solver.lazy-wheel`; any primary source disables the implicit PyPI; source priority `default` deprecated; an inconsistent lock file is an error; `to` in `tool.poetry.packages`; the `keyring.enabled` setting; `poetry build --output` and `poetry publish --dist-dir`.	Basic Usage
2.0.0 (2025-01-05)	The PEP 621 `[project]` table; `[tool.poetry.requires-plugins]`; lock file 2.1 with markers and groups and the `installer.re-resolve` setting; `poetry lock` keeps locked versions (`--regenerate` for the old behaviour); `poetry sync`; `poetry env activate`; `poetry export` and `poetry shell` no longer included; `add --optional` takes an extra; `-C` really changes directory; `--project`; `include` entries without `format` go to the sdist only; settings renamed (`config --migrate`); Python 3.8 dropped. poetry-core 2.0 deprecates `tool.poetry.dev-dependencies`.	Migrating to Poetry 2
2.1.0 (2025-02-15)	`poetry build` works with any build back end; experimental `poetry python install/list/remove`; `poetry new` uses the `src` layout; the experimental `installer.build-config-settings`; adding a source without `--priority` deprecated.	Environments
2.2.0 (2025-09-14)	PEP 735 `[dependency-groups]` and nested groups (`include-groups`); PEP 639 license expressions and `license-files`; normalised group names; `poetry show --format json`; Python 3.14.	Groups
2.3.0 (2026-01-18)	`installer.re-resolve` defaults to `false`; PEP 735 groups count in the lock file’s hash (so 2.2.x sees a 2.3 lock as outdated); `pylock.toml` export (with the export plugin); build constraints for dependencies; editable project plugins; Python 3.9 dropped.	Lock files
2.3.3 (2026-03-29), 2.3.4 (2026-04-12)	Security: path traversal fixed in the wheel installer (2.3.3) and in sdist extraction on Python 3.10.0–3.10.12 and 3.11.0–3.11.4 (2.3.4).	Supply chain
2.4.0 (2026-05-03)	`solver.min-release-age` with its two exclusion settings; `poetry update <name>` errors for a name that is not a dependency; a trailing slash added to upload URLs.	Configuration
2.4.2 (2026-08-29)	Security: path traversal when downloading from a compromised URL or source, another in sdist extraction; no longer installs an artefact missing from the lock file when the source gives no hash.	Supply chain
2.5.0 (2026-09-19), 2.5.1 (2026-09-20)	`installer.builtin-uninstall`; Python 3.15; credentials for an `https` repository never sent over `http`; credentials no longer mixed up between repositories on one host; an error when the current Python does not fit the project and `virtualenvs.create = false`; many performance improvements.	Configuration

1.2.0 (2022-08-31)

The standalone installer (install.python-poetry.org); dependency groups, including optional ones ([tool.poetry.group.<name>]), the plugin system, the poetry self commands, poetry export moved to poetry-plugin-export, Dulwich instead of the git command, install --sync, installer.no-binary, single-page link sources; the old get-poetry.py installer deprecated.

Groups, Plugins

1.3.0 (2022-12-09)

Lock file format 2.0.

Lock File

1.4.0 (2023-02-27)

A modern installer independent of pip (installer.modern-installation); the old installer deprecated.

1.5.0 (2023-05-19)

Source priority with supplemental and explicit; the default and secondary flags deprecated; the implicit PyPI’s priority configurable.

Sources

1.6.0 (2023-08-20)

poetry check --lock replaces poetry lock --check; Python 3.7 dropped.

check

1.7.0 (2023-11-03)

Python 3.12; poetry version --next-phase; the poetry-install pre-commit hook; a warning that poetry-plugin-export will stop being installed by default.

1.8.0 (2024-02-25)

package-mode = false for projects that only manage dependencies; PEP 658 metadata and solver.lazy-wheel; any primary source disables the implicit PyPI; source priority default deprecated; an inconsistent lock file is an error; to in tool.poetry.packages; the keyring.enabled setting; poetry build --output and poetry publish --dist-dir.

Basic Usage

2.0.0 (2025-01-05)

The PEP 621 [project] table; [tool.poetry.requires-plugins]; lock file 2.1 with markers and groups and the installer.re-resolve setting; poetry lock keeps locked versions (--regenerate for the old behaviour); poetry sync; poetry env activate; poetry export and poetry shell no longer included; add --optional takes an extra; -C really changes directory; --project; include entries without format go to the sdist only; settings renamed (config --migrate); Python 3.8 dropped. poetry-core 2.0 deprecates tool.poetry.dev-dependencies.

Migrating to Poetry 2

2.1.0 (2025-02-15)

poetry build works with any build back end; experimental poetry python install/list/remove; poetry new uses the src layout; the experimental installer.build-config-settings; adding a source without --priority deprecated.

Environments

2.2.0 (2025-09-14)

PEP 735 [dependency-groups] and nested groups (include-groups); PEP 639 license expressions and license-files; normalised group names; poetry show --format json; Python 3.14.

Groups

2.3.0 (2026-01-18)

installer.re-resolve defaults to false; PEP 735 groups count in the lock file’s hash (so 2.2.x sees a 2.3 lock as outdated); pylock.toml export (with the export plugin); build constraints for dependencies; editable project plugins; Python 3.9 dropped.

Lock files

2.3.3 (2026-03-29), 2.3.4 (2026-04-12)

Security: path traversal fixed in the wheel installer (2.3.3) and in sdist extraction on Python 3.10.0–3.10.12 and 3.11.0–3.11.4 (2.3.4).

Supply chain

2.4.0 (2026-05-03)

solver.min-release-age with its two exclusion settings; poetry update <name> errors for a name that is not a dependency; a trailing slash added to upload URLs.

Configuration

2.4.2 (2026-08-29)

Security: path traversal when downloading from a compromised URL or source, another in sdist extraction; no longer installs an artefact missing from the lock file when the source gives no hash.

Supply chain

2.5.0 (2026-09-19), 2.5.1 (2026-09-20)

installer.builtin-uninstall; Python 3.15; credentials for an https repository never sent over http; credentials no longer mixed up between repositories on one host; an error when the current Python does not fit the project and virtualenvs.create = false; many performance improvements.

Configuration

Announced but not yet done (in every release post from 2.1 to 2.5): when pyproject.toml has no [build-system], Poetry will fall back to setuptools, as PEP 517 says, instead of poetry-core. Poetry 2.5.1 still uses poetry-core and prints a warning, so always declare [build-system]. The 2.5 post also plans to make installer.builtin-uninstall the default later.

Upgrade to 2.4.2 or later for the security fixes; every 2.x release before it is affected by at least one of the path traversal issues.

Source: Poetry history: 2.5.0, 2.4.0, 2.3.0, 2.2.0, 2.1.0, 2.0.0, 1.2.0, Announcing Poetry 1.2.0, 1.5.0, 1.8.0, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, Poetry changelog.

Pinning the Poetry a project needs

Since 2.0 (requires-poetry is checked before any other validation since 2.3), a project can state the Poetry versions that may manage it, and any other Poetry refuses to work on it. With requires-poetry = ">=3.0" both poetry check and poetry install stop with exit code 1:

[tool.poetry]
requires-poetry = ">=2.4.2,<3.0"

This project requires Poetry >=3.0, but you are using Poetry 2.5.1

Check the running version with poetry --version (Poetry (version 2.5.1)) or poetry about, which also prints the poetry-core version (Poetry-Core Version: 2.5.0). In CI pin it explicitly (pipx install poetry==2.5.1; see CI Caching & Containers). The lock file records the Poetry that wrote it in its header comment (# This file is automatically @generated by Poetry 2.5.1 …) and its format in lock-version (2.1). Poetry 2.5.1 reads formats 1.x and 2.x: a newer 2.x format gets the warning The lock file might not be compatible with the current version of Poetry., a 3.x format the error The lock file is not compatible with the current version of Poetry.

Source: Poetry: requires-poetry.

Compared with pip

pip uses calendar-based YY.N versions released quarterly and supports only its latest release (see pip: Versions & Release History). Poetry uses major.minor.micro versions where a minor release may remove deprecated features; both tools ask you to read the changelog before upgrading.