🐍

Poetry v2 への移行でやったこと

2025/01/21に公開

今年の年始早々、1月5日に Python のパッケージ管理ツールの一つである Poetry の v2.0.0 がリリースされました。破壊的な変更も含まれており、特に Poetry のバージョンを指定せずにチームで利用していた場合など、対応が必要かと思います。
私の参画するプロジェクトでも v2 への移行を行いましたので、具体的な作業内容を記録しておきます。

参考

公式のアナウンスはこちらです。
https://python-poetry.org/blog/announcing-poetry-2.0.0/

日本語ではこちらの記事が非常に分かりやすいです。本記事ではこちらの記事に記載されていない部分に重点を置いて説明していますので、併せて読んでいただくと良いと思います。
https://zenn.dev/hikaelis/articles/98c17f52754a64

Poetry のバージョン固定

開発環境は devcontainer を使ってチームで統一していましたが、 Poetry のバージョンを指定していませんでした。 lock ファイルの形式が変更されているため、放置しているとバージョン差異に起因するコンフリクトが発生する可能性があります。1月11日に v2.0.1 が公開されているため、そちらに統一しました。

.devcontainer/Dockerfile
RUN pip install poetry==2.0.1

GitHub Actions の workflow ファイル内でも同様にバージョンを指定しました。
FastAPI の本番環境用の Dockerfile も同様に修正しました。

...
RUN pip install poetry==2.0.1 &&\
    poetry install --only main
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]

pyproject.toml の修正

tool.poetry セクションのフィールドの多くが project セクションに置き換えられています。

BEFORE

[tool.poetry]
name = "sample-product"
version = "0.1.0"
description = "This is a sample product."
authors = ["Shohei Ohtani <shohei@example.com>"]
readme = "README.md"

AFTER

[project]
name = "sample-product"
version = "0.1.0"
description = "This is a sample product."
authors = [{ name = "Shohei Ohtani", email = "shohei@example.com" }]
readme = "README.md"
requires-python = "^3.10"
dynamic = ["dependencies"]

authors

authors の指定方法(型)が変わっています。

requires-python

requires-python で Python のバージョンを記載する必要があります。[tool.poetry.dependencies] セクションの先頭で指定しているのと同じものをこちらにも記載しました。

dependencies

dependencies に関しては、これまでの tool.poetry.dependencies から project.dependencies に移行することも可能です。ただし tool.poetry.dependencies でしかサポートされていない機能もあり、非推奨になったわけではありません。私の場合は tool.poetry.dependencies を使い続けることを選択しました。この場合は、 [project.dynamic] に dependencies を追加する必要があります。

README の修正とエンジニアへのアナウンス

コマンドについても使えなくなったものや変更されたものがあります。これらは README に反映するとともにエンジニアにその旨をアナウンスしました。

poetry shellpoetry env activate

poetry shell が使えなくなりました。代わりに

poetry env activate

が使えます。

poetry lock --no-updatepoetry lock

poetry lock

がデフォルトで --no-update の挙動をするようになりました。

poetry lockpoetry lock --regenerate

以前の poetry lock にあたるコマンドは

poetry lock --regenerate

です。

Discussion