Poetry は、Python の依存管理・仮想環境・パッケージ公開をまとめて扱うツールです。 pyproject.toml と ロックファイル を軸に、環境を再現できる形で依存を管理します。
pip + venv と何が違うのか
pip は「入れる」だけの道具でした。Poetry はそこに依存解決とロックを足します。
- 依存解決：ライブラリ同士のバージョン要求を突き合わせ、成立する組み合わせを探す
- ロック：解決した結果を
poetry.lockに固定する。別のマシンでも同じ組み合わせが入る
「自分の環境では動くのに他の人の環境で動かない」を減らすのが目的です。pip の requirements.txt でも近いことはできますが、依存の依存まで含めて固定する強さが違います。
直接依存と間接依存を分けて書く
pyproject.toml に書くのは自分が直接使うライブラリだけです。その先の依存はロックファイルが持ちます。ここを混同して pip freeze の出力をそのまま pyproject.toml へ貼ると、更新のたびに手作業が発生します。
押さえておきたい注意点
いちばん多いつまずきは、Poetry 自体をプロジェクトの仮想環境の中に入れてしまうことです。Poetry は環境を管理する側なので、管理される側の中に置くと自分自身を壊しかねません。公式のインストーラや pipx を使い、プロジェクトの外に置いてください。
また、依存解決は組み合わせ探索なので、依存が多いプロジェクトでは待ち時間が長くなります。ここが後発の uv が支持を集めた主因のひとつです。