poetry-plugin-freeze

1.2.0 verified Sat May 09 auth: no python

A Poetry plugin that freezes a wheel's dependency versions based on the current lock file, ensuring reproducible builds. Version 1.2.0 supports both Poetry v1 and v2, and requires Python ≥3.9.

pip install poetry-plugin-freeze==1.2.0

Common errors

error ModuleNotFoundError: No module named 'poetry.plugins' ↓

cause Trying to import the plugin directly in Python code. This is a CLI plugin, not a Python library.

fix

Do not import it; use as a Poetry CLI command: poetry freezer.

error Poetry cannot find the plugin after pip install ↓

cause The plugin must be installed into Poetry's environment via `poetry self add`, not just `pip install`.

fix

Run poetry self add poetry-plugin-freeze to register the plugin.

error ValueError: Unsupported poetry version ↓

cause Using an older plugin version with Poetry v2.

fix

Upgrade to poetry-plugin-freeze==1.2.0 which supports Poetry v2.

Warnings

breaking Poetry v2 support requires plugin version >=1.2.0. Older versions (<=1.1.0) are incompatible with Poetry v2. ↓

fix Upgrade to poetry-plugin-freeze==1.2.0 or later.

gotcha The plugin does NOT freeze dev dependencies. Only main dependencies from the lock file are included. ↓

fix Ensure your dev dependencies are not needed for runtime wheel execution, or use a different approach to freeze them.

deprecated The plugin is installed via `poetry self add`, not `pip install`. Using `pip install` will install the package but it won't be recognized as a Poetry plugin until you also run `poetry self add`. ↓

fix Run `poetry self add poetry-plugin-freeze` after `pip install` or directly `poetry self add`.

Quickstart

After installing the plugin, use `poetry freezer freeze` to embed pinned dependency versions from the lock file into a wheel.

poetry self add poetry-plugin-freeze
poetry build
# To freeze dependencies for a specific wheel:
poetry freezer freeze --file dist/*.whl --lock poetry.lock --output frozen_wheel.whl