Pythonでの開発にPoetryを使っていると、必ず目にするのがpoetry.lockというファイルです。結論から言うと、poetry.lockがあることで「同じコードなのに環境によって動いたり動かなかったりする」問題を大幅に減らせます。依存関係の解決結果を固定し、開発者・CI・本番環境で同じライブラリ構成を再現しやすくなる点が最大の変化です。
一方で、「とりあえず入れておけば安心」という魔法のファイルではなく、使い方や前提を誤ると、更新の停滞や意図しない差分を生むこともあります。この記事では、poetry.lockがあると具体的に何が変わるのか、実際の挙動や失敗しがちなポイントを交えながら、現実的な視点で整理していきます。
poetry.lockとは何を記録しているのか
poetry.lockは、Poetryが依存関係を解決した「結果」を保存するファイルです。pyproject.tomlには「要求条件」が書かれ、poetry.lockには「実際に使うと決まったバージョン一覧」が書かれます。
例えば、pyproject.tomlに次のような指定がある場合を考えます。
[tool.poetry.dependencies] python = "^3.10" requests = "^2.31" || この指定だけでは、requestsのどのマイナーバージョンや依存ライブラリが入るかは環境やタイミングに左右されます。Poetryが依存関係を解決すると、その結果がpoetry.lockに詳細に書き込まれます。 - 実際にインストールするrequestsの正確なバージョン - requestsが依存しているライブラリのバージョン - それぞれのハッシュ値 この情報があることで、同じpoetry.lockを使えば、ほぼ同じ環境を再現できます。 * poetry.lockがあると何が変わるのか ** インストール結果が安定する poetry.lockが存在する状態でpoetry installを実行すると、Poetryは原則としてlockファイルの内容を優先します。そのため、開発者Aの環境、開発者Bの環境、CI環境で入るライブラリ構成が揃いやすくなります。 実際の現場では「昨日まで動いていたのに、今日cloneしたらテストが落ちる」というトラブルが頻繁に起きます。これは依存関係の解決結果が毎回微妙に変わることが原因であるケースが少なくありません。poetry.lockがあることで、この種の問題はかなり減ります。 ** CIや本番環境とのズレが減る CIでpoetry installした結果と、ローカルでの結果がズレると、テストは通るのにデプロイ後にエラーが出るといった事態につながります。poetry.lockをリポジトリに含めておけば、CIでも同じ依存関係を使いやすくなります。 特に、Dockerを使ったビルドではpoetry.lockの有無が効いてきます。lockがあることで、イメージビルドの再現性が高まり、デバッグもしやすくなります。 ** 依存関係の変更が意識的になる poetry.lockがあると、依存関係を更新した際に差分がはっきり見えるようになります。ライブラリを追加・更新した結果、どの依存が変わったのかがGitの差分として確認できます。 これは地味ですが重要で、「いつの間にか依存関係が変わっていた」という状況を防ぐ助けになります。 * poetry.lockがない場合に起きやすいこと poetry.lockを使わず、pyproject.tomlだけで運用している場合、次のような問題が起きやすくなります。 - インストールのたびに微妙に違うバージョンが入る - 他人の環境で再現しないバグが出る - CIでだけ失敗するテストが増える 特に長期間メンテナンスされるプロジェクトほど、これらの問題は積み重なりやすくなります。 * 実際にやるとこうなる：poetry.lockの挙動 ** 新規環境でのインストール リポジトリにpoetry.lockが含まれている状態で、新しい環境にcloneしてpoetry installを実行すると、Poetryはlockの内容を元にインストールを行います。 >|sh| poetry install || このとき、pyproject.tomlに「^2.31」と書いてあっても、lockに2.31.0と書かれていれば、そのバージョンが選ばれます。 ** 依存関係を更新した場合 poetry updateを実行すると、poetry.lockが再計算され、条件を満たす範囲で新しいバージョンが選ばれます。 >|sh| poetry update || この操作は意図的に行うべきで、「なんとなくupdateしたら大量に差分が出た」という事態を避けるためにも、実行タイミングはチームで共有しておくのが無難です。 * 向いているケース・そうでないケース poetry.lockは多くのプロジェクトで有効ですが、万能ではありません。 ** 向いているケース - チーム開発や複数環境での運用 - CI/CDを使った自動テスト・デプロイ - 中長期で保守されるプロジェクト これらの場合、再現性の高さは大きなメリットになります。 ** 注意が必要なケース - ライブラリ開発で依存の幅を検証したい場合 - 利用者側にlockを強制したくないケース ライブラリそのものを配布する場合、poetry.lockを同梱しない選択もあります。このあたりは目的次第です。 * リスクや注意点 poetry.lockがあることで、依存関係の更新が「止まりやすくなる」という側面もあります。lockを長期間更新しないと、脆弱性修正が入らないままになる可能性があります。 そのため、 - 定期的にpoetry updateを検討する - セキュリティアラートが出たら更新を優先する といった運用ルールを決めておくことが重要です。lockがあるから安心、ではなく、lockをどうメンテナンスするかが問われます。 * ありがちな誤解 「poetry.lockがあれば、完全に同一環境になる」と思われがちですが、OSやPython本体のバージョン差までは吸収できません。あくまでPythonパッケージの範囲での再現性向上だと理解しておく必要があります。 * 結局どうすればいいか poetry.lockは、Pythonプロジェクトの依存関係管理を現実的に安定させるための重要な仕組みです。アプリケーション開発やチーム開発では、基本的にコミットして使う前提で問題ありません。
