Poetryは、Pythonの依存関係管理・仮想環境・パッケージのビルドと公開を、pyproject.toml一枚に集約するツールです。本記事では、requirements.txtによる運用が壊れる仕組みから、インストール、poetry add と poetry install の使い分け、pyproject.tomlとpoetry.lockの役割分担までを実際のコマンド付きで整理します。あわせて、2025年1月の2.0で変わった poetry shell の扱いやPEP 621対応、2026年9月時点の最新2.4.3までに加わった poetry sync とpylock.toml書き出しも、公式ドキュメントの記述に当たりながら押さえます。pip・pipenv・uv・condaとの比較、そしてどの規模で採用しどこでは見送るかの線引きまで扱う内容です。
まとめ：Poetryを採用する条件と見送る条件の結論
Poetryは、依存の宣言をpyproject.tomlに、解決結果をpoetry.lockに分けて持たせることで、pipとrequirements.txtでは崩れがちだった環境の再現性を仕組みで固定するツールです。仮想環境の作成、依存解決、wheelとsdistのビルド、PyPIへの公開までを一つのコマンド体系で扱えます。公式のリリース履歴によると、2026年9月時点の最新は2.4.3で、公開日は2026年9月5日でした。公式のインストールドキュメントが示す動作要件はPython 3.10以上です。
2.0での変更を知らないまま古い記事をなぞると、ほぼ確実に詰まります。poetry shell はコアから外れてpoetry-plugin-shellへ移り、標準は poetry env activate になりました。poetry export もプラグイン化され、poetry self add poetry-plugin-export を打たないと呼び出せません。メタデータはPEP 621の [project] テーブルへ寄せる方針に変わり、依存グループと package-mode だけが [tool.poetry] 側に残ります。
採用の線引きを先に書きます。複数人で開発し、依存が数十を超え、CIとDockerで同じ環境を再現したいならPoetryを入れる価値が出ます。逆に、依存が3つ程度で数週間のうちに役目を終えるスクリプトや、GPU向けのネイティブ依存が中心の解析環境では見送ってください。前者はvenvとpipで足り、後者はcondaのほうが守備範囲に合います。すでにPoetryで回っているプロジェクトを、速度だけを理由にuvへ移すのも勧めません。判断の根拠は、本文の比較章で条件を添えて示します。
Poetryが解決するPython依存関係管理が抱える構造的な課題
Pythonでの開発が大規模になるほど、ライブラリの依存関係をどう管理するかという問題は無視できなくなります。従来のpipとrequirements.txtによる管理は手軽な反面、再現性やバージョンの整合性という面で構造的な限界を抱えていました。この章では、Poetryが登場した背景にある依存関係管理の課題を整理し、なぜ専用ツールが必要とされるのかを明らかにします。
requirements.txtによる管理が破綻する3つの典型的な失敗パターン
requirements.txtはPythonで最も普及した依存管理の方法ですが、プロジェクトが成長すると管理が破綻しやすくなります。とくに複数人での開発や長期運用の場面では、次の3つの失敗が繰り返し起こりがちです。
- バージョンを固定せずパッケージ名だけを記載した結果、開発環境と本番環境で異なるバージョンが入り、動作が再現しなくなる失敗
- 直接依存するライブラリだけを書き、そのライブラリがさらに必要とする下位パッケージ（推移的依存）のバージョンが管理対象から漏れる失敗
- requirements.txtを手作業で更新するため、不要になった依存が削除されず、ファイルが肥大化したまま放置される失敗
これらはいずれも、requirements.txtが「入れたいものを書くファイル」であって「実際に入った状態を記録するファイル」ではない点に起因します。Poetryはこの役割を明確に分離しました。宣言用のpyproject.tomlと記録用のpoetry.lockを使い分けることで、上記の破綻を構造的に防いでいるのです。
推移的依存が原因で起こるバージョン競合の具体的な発生メカニズム
パッケージは単独で動くわけではなく、内部で別のパッケージを利用しています。あるライブラリAがライブラリCの1系を必要とし、別のライブラリBが同じCの2系を必要とする場合、両者を同時に入れようとすると競合が発生します。これが推移的依存によるバージョン競合の典型的な構図です。
pipはインストール時に依存関係を逐次解決していくため、後から入れたパッケージが先に入れたパッケージの依存を上書きしてしまうことがあります。その結果、表面上はインストールが成功していても、実行時に予期しないエラーへとつながるのです。Poetryはインストール前にすべての依存関係をまとめて解析し、矛盾のない組み合わせを見つけてから導入を行います。解決できない組み合わせはエラーとして明示されるため、問題の所在が一目で分かりやすくなる点も大きな利点でしょう。実際、依存の数が増えるほど手作業での競合解消は現実的でなくなり、自動解決の価値はいっそう高まります。Poetryを使えば、開発者は競合の有無を逐一気にせず実装に集中できるのです。
pip単体では確保できない環境再現性とロックファイル不在の弊害
環境再現性とは、別のマシンや別のタイミングでまったく同じ依存構成を再現できる性質を指します。pip単体ではこの再現性を担保する仕組みが弱く、同じrequirements.txtからでも実行のたびに少しずつ異なるバージョンが入る可能性があります。これは依存の解決結果を記録しておくロックファイルが標準で存在しないことが原因です。
ロックファイルがあれば、依存パッケージの厳密なバージョンと配布物のハッシュ値まで固定でき、改ざんや想定外の更新を検知できます。pip単体でこれを実現するには、ハッシュ付きのrequirements.txtを別途生成する追加運用が要ります。手間がかかるうえに抜け漏れも起きやすく、運用の負担は小さくありません。その点Poetryはpoetry.lockによって記録を自動で管理するため、チーム全員が同一の環境を簡単に再現できます。さらに、誰かが依存を更新すればロックファイルも一緒に変わるので、変更の履歴をコードと同じ流れで追跡できるのも実務上の強みです。
グローバル環境への直接インストールが招くプロジェクト間の汚染
pipでパッケージを仮想環境を使わずに導入すると、システム全体で共有されるグローバル環境へ直接インストールされます。この状態では、あるプロジェクトのために入れたパッケージが、別のプロジェクトにも影響を及ぼしてしまうのです。たとえばプロジェクトAが古いバージョンを必要とし、プロジェクトBが新しいバージョンを必要とするとしましょう。片方を更新すると、もう片方が動かなくなるという衝突が起こります。
こうしたプロジェクト間の汚染は、原因の特定が難しい不具合の温床になりがちです。本来は各プロジェクトごとに独立した依存環境を用意すべきなのに、その分離が徹底されないまま開発が進んでしまうわけです。Poetryはプロジェクトごとに専用の仮想環境を自動で作成し、依存を完全に切り離します。これにより、プロジェクトをまたいだ予期しない副作用を根本から避けられるのです。結果として、環境に起因する不具合の調査に時間を奪われる場面が減り、開発の生産性も維持しやすくなります。プロジェクトの数が増えても破綻しにくいのは、この自動分離があるからこそでしょう。
Poetryが単一ツールで統合する依存解決とビルド処理の範囲
従来のPython開発では、依存管理にpip、設定にsetup.pyやsetup.cfg、ビルドにsetuptools、公開にtwineといった具合に、目的ごとに別々のツールを組み合わせる必要がありました。役割が分散していると学習コストが上がり、設定が複数ファイルに散らばって全体像をつかみにくくなります。Poetryはこれらの工程を一つのツールに統合した点に大きな価値があります。
具体的には、依存関係の宣言と解決、仮想環境の作成と管理、配布パッケージのビルド、PyPIへの公開までを一貫して扱えます。設定はpyproject.tomlという単一のファイルに集約され、プロジェクトの全体像が把握しやすくなりました。複数のツールを横断的に覚える負担が減り、開発者は本来の実装に集中しやすくなるのです。加えて、設定ファイルが標準化されることで、エディタの補助機能や各種ツールとの連携も取りやすくなります。一つのツールに統合されているからこそ、依存の追加からビルド、公開までを同じ操作感で扱えるのも見逃せない利点でしょう。Poetryを軸に据えることで、プロジェクトの構成管理は驚くほどシンプルになります。
setup.pyとrequirements.txt二重管理から脱却する利点
配布を前提としたPythonパッケージでは、依存をrequirements.txtに、メタデータや配布用の依存をsetup.pyにと、同じ情報を二か所に書き分ける二重管理が長く課題でした。記述場所が分かれていると更新漏れが起きやすく、両者の内容が食い違う原因にもなります。Poetryはこの二重管理を解消する設計思想を持っています。
| 観点 | 従来手法（pip + setup.py） | Poetry |
|---|---|---|
| 依存の記述場所 | 2ファイルに分散 | pyproject.toml に集約 |
| 固定バージョンの記録 | 手動管理（標準のロックなし） | poetry.lock で自動記録 |
| ビルド・公開の設定 | setup.py や別ファイルで個別定義 | 同一ファイル内で一元管理 |
このように、Poetryでは依存もメタデータもビルド設定もpyproject.tomlへ集約されるため、情報の食い違いが起こりにくくなります。設定ファイルが一つにまとまることで、新しくプロジェクトに参加した開発者も構成を素早く理解できるのです。結果として、二重管理に伴うメンテナンスの負担が大幅に軽くなります。
Poetryのインストール手順と環境別バージョン選定の判断基準
Poetryを使い始めるには、まず自分の環境に合った方法で導入する必要があります。導入方法はいくつかあり、システムへの影響度や更新のしやすさはそれぞれ異なるのです。この章では、代表的なインストール方法の比較とOS別の具体的なコマンド、そしてバージョン選定や更新の判断基準を順に解説します。
公式インストーラとpipx経由の2つの導入方法における明確な違い
Poetryの導入で広く推奨されるのは、pipxを使う方法と公式インストーラを使う方法の2つです。公式のインストール手順は、この2つに手動インストールを加えた3経路を示し、先頭にpipxを置いています。どちらもPoetry自体をプロジェクトの依存から切り離して管理できる点は共通する一方、性質には違いがあるのです。なお同ページはPoetry本体の動作要件をPython 3.10以上と明記しており、3.9以前のシステムPythonしか無い環境では先にPythonを用意する必要があります。
| 比較観点 | 公式インストーラ | pipx |
|---|---|---|
| 分離の仕組み | 専用の仮想環境を自動作成 | ツールごとに隔離環境を作成 |
| 更新方法 | poetry self update | pipx upgrade poetry |
| 前提条件 | 追加ツール不要 | 事前にpipxの導入が必要 |
公式インストーラはPython本体さえあればすぐ導入でき、Poetryを独立した環境に隔離してくれます。一方pipxは複数のコマンドラインツールをまとめて管理したい人に向いており、Poetry以外のツールも同じ流儀で扱えるのが強みです。すでにpipxを使っているならpipxで揃え、そうでなければ公式インストーラを選ぶとよいでしょう。
Windows・macOS・Linux別に異なるインストールコマンドの実例
公式インストーラを使う場合、コマンドはOSによって異なります。macOSとLinuxではシェルからスクリプトを取得して実行し、WindowsではPowerShellを使うのが基本です。以下に各環境での実際のコマンドを示します。
公式インストーラのコマンドはOSで分かれます。以下は公式ドキュメントに記載された導入コマンドと、導入直後に打つ確認コマンドです。そのままコピーして実行できます。
# macOS / Linux（公式インストーラ）
curl -sSL https://install.python-poetry.org | python3 -
# Windows（PowerShell）
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
# pipx（OS共通・公式ドキュメントが先頭に挙げる方法）
pipx install poetry
# 導入確認（版番号が返れば成功）
poetry --versionバージョンが表示されない場合は、後述するPATH設定の問題を疑ってください。公式インストーラの配置先はOSごとに決まっており、macOSは ~/Library/Application Support/pypoetry、Linuxは ~/.local/share/pypoetry、Windowsは %APPDATA%\pypoetry です。実行ファイルの場所を探すときは、まずこの3か所を見ると早く片付きます。
システムPythonを汚さないための推奨インストール方法の判断基準
避けたいのは、OSに最初から入っているシステムPythonへ pip install poetry で直接インストールすることです。システムPythonにツールを追加すると、OSの動作が依存するパッケージと競合する恐れがあり、環境全体を不安定にしかねません。Poetry自体をプロジェクトの依存と混在させてしまう点も問題になります。
判断基準はシンプルで、Poetryは必ず独立した環境に隔離して導入するのが安全だと考えてください。公式インストーラやpipxはまさにこの隔離を自動で行うため、推奨される選択肢になります。どうしてもpipで入れる場合でも、システムPythonではなくユーザー領域や専用の仮想環境を対象にすべきです。原則として「システムPythonには手を加えない」という方針を守ることが、トラブルを避ける最も確実な近道でしょう。なお、仮想環境を自動で扱うPoetryに任せておけば、システムPythonを意識する場面はほとんどなくなります。導入時のひと手間を惜しまない姿勢が、後々の安定した運用につながるのです。
poetry self updateで実施するバージョン更新と固定の手順
公式インストーラで導入したPoetryは、専用コマンドで簡単に更新できます。最新版へ上げたいときは poetry self update を実行するだけで、Poetry本体だけが安全に更新されます。プロジェクトの依存には一切影響しないのが、この方式の利点です。
一方で、チーム開発やCI環境では、全員が同じPoetryバージョンを使えるかどうかが再現性を左右します。特定のバージョンに固定したい場合は poetry self update 2.4.3 のようにバージョンを指定して実行します。公式のリリース履歴によれば、2026年9月時点の最新は2.4.3（2026年9月5日公開）で、2.4系は2026年5月の2.4.0から続く系列です。さらにPoetry 2.0以降では、pyproject.tomlに必要なPoetryバージョンを宣言する仕組みも加わりました。想定外のバージョンで操作された際に警告を出せるため、チーム全体の足並みを揃えやすくなります。CIでローカルと異なるPoetryバージョンが使われると、手元で通ったはずの処理が落ちることもあるのです。版を明示しておけば、こうした環境差による不可解なトラブルの大半は消えます。
インストール失敗時に確認すべきPATH設定の典型的なつまずき
導入直後に poetry コマンドが見つからないというエラーは、初心者が最もつまずく箇所です。これはPoetryの実行ファイルが置かれた場所が、シェルの検索パスであるPATHに登録されていないために起こります。インストール自体は成功しているのに使えない、という状態に陥りがちです。
多くの場合、実行ファイルはユーザーのホーム配下の隠しディレクトリに配置されます。macOSやLinuxでは、設定ファイルに export PATH="$HOME/.local/bin:$PATH" のような記述を追加し、シェルを再起動すると解決することがほとんどです。Windowsの場合は環境変数の設定画面からインストール先のパスを追加します。設定後にターミナルを開き直すのを忘れると変更が反映されないため、その点には注意してください。PATHの書き方はOSやシェルの種類によって変わるので、自分の環境に合った手順を確認することが大切です。一度正しく通してしまえば、以降は意識せずPoetryを呼び出せるようになります。
Poetry 2.0系と1.x系の主要な変更点と移行時の注意点
2025年1月5日にリリースされたPoetry 2.0は、1.x系から複数の破壊的な変更を含みます。1.x系の情報をそのまま参照すると挙動が食い違うため、移行時には変更点の把握が前提です。とくにコマンド構成の変化は実務に直結します。公式リポジトリのリリースノートと、公式サイトの履歴ページが一次情報です。
- PEP 621に準拠した
[project]テーブルでメタデータを記述できるようになり、従来の[tool.poetry]の一部項目が非推奨化された poetry shellがコアから外れ、組み込みのpoetry env activateが推奨に変わった（従来の挙動はプラグインで利用可能）- 依存を書き出す
poetry exportが既定では同梱されなくなり、プラグインとして別途用意する形に変わった
このほか、2.0ではPython 3.8のサポートが外れて最低要件が3.9へ上がり、その後さらに3.10以上へ引き上げられました。poetry install --sync から poetry sync への移行も加わっています。1.x系を前提に書かれた記事や社内手順を流用する際は、これらが現行版と一致しているかを確認してください。コマンドが見つからないときは、まずプラグインの分離を疑うと切り分けが早く済みます。2.1以降で加わった仕様は、後半の専用章でまとめて扱います。
Poetryを用いた仮想環境構築とプロジェクト初期化の実践手順
Poetryの大きな魅力は、プロジェクトごとに独立した仮想環境を自動で用意してくれる点にあります。環境の分離を意識せずに作業を始められる一方で、仮想環境の作成先や有効化の方法には知っておくべき要点がいくつかあるのです。この章では、プロジェクトの初期化から仮想環境の確認・実行までを、実際のコマンドとともに順を追って解説します。なお、Poetryが作る仮想環境はvenvと同じ隔離レベルで、コンテナや仮想マシンとは守備範囲が異なるものです。隔離の段階ごとの違いは仮想環境の種類と隔離レベルの解説で整理しています。
poetry newとpoetry initで作るプロジェクト雛形の使い分け
新しくPoetryプロジェクトを始める方法は大きく2つあります。ゼロから標準的なディレクトリ構成ごと用意したいときに使うのが poetry new myproject です。これを実行すると、ソース用のフォルダやテスト用のフォルダ、設定ファイルまでをまとめて生成してくれます。一方で、すでにファイルが存在する既存のフォルダにPoetryを導入したい場合は poetry init が適しています。
両者の違いは、雛形ごと作るか、設定ファイルだけを作るかにあります。poetry init は対話形式で質問に答えていくだけで、既存の構成を壊さずにpyproject.tomlを生成できるのが利点です。これから新規に作るなら poetry new、途中から取り入れるなら poetry init という基準で選ぶと迷いません。プロジェクトの状態に合わせて使い分けることが、スムーズな立ち上げの第一歩になるでしょう。なお poetry new で作られる構成は標準的な配置に沿っているため、後からチームメンバーが参加しても迷いにくいという利点もあります。
仮想環境の作成先をプロジェクトディレクトリ内に変える設定手順
Poetryは既定では、ユーザー共通のキャッシュ領域に仮想環境を作成します。この方式は管理が楽な反面、環境がプロジェクトの外に置かれるため、フォルダごと持ち運んだりエディタから認識させたりする際に分かりにくいのです。そこで、仮想環境をプロジェクトの直下に作る設定がよく使われます。
設定は poetry config virtualenvs.in-project true を一度実行するだけで完了します。以降に作成される仮想環境は、プロジェクト内の .venv というフォルダにまとめられるようになります。この方式なら、環境の所在が一目で分かり、エディタ側でも自動的に認識されやすくなるのが利点です。ただし .venv はバージョン管理の対象から除外しておくべきなので、無視設定への追加を忘れないようにしましょう。プロジェクト単位で環境が完結する構成は、チーム内での再現性を高めるうえでも有効です。環境をプロジェクトと一緒に扱えるため、新しいメンバーがフォルダを取得したあとの初期設定もスムーズに進みます。
poetry envコマンドで確認する仮想環境のパスとPythonバージョン
Poetryがどの仮想環境を使っているのかを把握しておくと、原因不明のトラブルを1段階減らせます。現在の環境の詳細を確認したいときは poetry env info を実行すると、仮想環境の場所や使用しているPythonのバージョンが表示される仕組みです。パスだけを知りたい場合は poetry env info --path を使うと簡潔に確認できます。
複数のPythonバージョンを切り替えながら開発する場面では、環境の一覧を表示する poetry env list も役立ちます。使用するPythonを明示的に指定したい場合は poetry env use 3.11 のようにバージョンを渡します。意図しないPythonで環境が作られていると、原因の分かりにくい不具合につながることがあるのです。日頃から使用中の環境を確認する習慣をつけておけば、こうした取り違えを早い段階で防げるでしょう。とくにチームで複数のPythonを併用している場合は、各自の環境がそろっているかを確かめる意味でも有効です。環境の取り違えは見落とされがちなだけに、確認の一手間が後の安心につながります。
poetry env activateとpoetry runによる仮想環境実行の使い分け
仮想環境内でコマンドを動かす方法は、用途によって使い分けます。単発のコマンドを実行したいだけなら poetry run python main.py のように、コマンドの前に poetry run を付けるのが手軽です。これなら環境を有効化する操作を挟まずに、その場で仮想環境の中身を使って実行できます。
対話的に作業を続けたい場合は、環境そのものを有効化します。Poetry 2.0以降では poetry env activate が組み込みの手段です。ここで一つ落とし穴があります。公式のCLIリファレンスは「このコマンドは仮想環境を有効化するのではなく、有効化用のコマンドを表示するだけ」と明記しています。実際に環境へ入るには、表示された行をシェルで評価する必要があるわけです。従来の poetry shell は2.0でコアから外れ、poetry-plugin-shellへ移りました。古い記事どおりに打って動かず戸惑う相談の多くは、この変更が原因です。連続して多くのコマンドを打つなら有効化、単発なら poetry run と覚えておけば迷いません。
既存プロジェクトへPoetryを後から導入する場合の具体的な移行手順
すでにpipとrequirements.txtで運用しているプロジェクトにも、Poetryを後から導入できます。いきなり全部を切り替えるのではなく、段階を踏んで移行するのが安全です。以下に、典型的な移行の流れを示します。
- プロジェクトのルートで
poetry initを実行し、対話形式でpyproject.tomlを生成する - requirements.txtに記載されている依存を確認し、
poetry addで一つずつ追加していく - 依存をすべて追加し終えたら
poetry installを実行し、poetry.lockを生成して環境を再構築する - 動作を確認できたら、不要になったrequirements.txtを整理し、ドキュメントを更新する
移行の途中では、バージョン指定の解釈がpipとPoetryで微妙に異なる点に気をつける必要があります。とくに、これまで緩く指定していた依存が厳密に解決されることで、思わぬ競合が表面化する場合があるのです。焦らず一つずつ確認しながら進めれば、安全に移行を完了できるでしょう。チーム開発であれば、移行のタイミングを事前に共有しておくとさらに混乱を防げます。
仮想環境が作られない・正しく認識されない場合の典型的な対処法
Poetryを使っていて、仮想環境がうまく作られない、あるいはエディタに認識されないという相談は少なくありません。よくある原因は、Poetryが参照しているPythonと、自分が使いたいPythonがずれていることです。まずは前述の poetry env info で、実際にどのPythonが使われているかを確認しましょう。
意図したバージョンでない場合は、poetry env use で正しいPythonを指定し直すと解決することが多くあります。環境が壊れていると感じたら、いったん削除して作り直すのも有効な手段です。エディタが認識しない場合は、仮想環境をプロジェクト直下に作る設定にしておくと、補完や実行が安定しやすくなります。それでも改善しないときは、PoetryやPython本体のバージョンが想定どおりかを順に切り分けていくとよいでしょう。原因を一つずつ潰していく姿勢が、結果的に最短の解決につながるのです。
pyproject.tomlとpoetry.lockが支える依存管理の仕組み
Poetryの依存管理は、役割の異なる2つのファイルによって支えられています。開発者が意図を書き込むpyproject.tomlと、解決結果を厳密に記録するpoetry.lockです。この2つの関係を理解すると、Poetryがなぜ高い再現性を実現できるのかが見えてきます。この章では、各ファイルの構造とバージョン指定の考え方を具体的に解説します。
pyproject.tomlに記述する依存関係とメタデータの基本構造
pyproject.tomlは、プロジェクトの設定を一か所に集約するための中心的なファイルです。ここにはプロジェクトの名前やバージョンといったメタデータと、必要な依存パッケージの一覧が記述されます。Poetry独自の記法では、依存は [tool.poetry.dependencies] というセクションにまとめて書きます。
たとえば、ある外部ライブラリを依存に加えると、このセクションにパッケージ名とバージョン制約が一行ずつ追記されていきます。多くの場合、手で直接編集するのではなく、後述するコマンドを通じて自動で書き込まれるのが基本です。手作業での書き換えは記述ミスのもとになるため、できるだけコマンドに任せるのが安全でしょう。pyproject.tomlを見れば、そのプロジェクトが何を必要としているかが一目で把握できるようになっています。設定が一つのファイルに整理されていることは、長期的な保守のしやすさにも直結します。
poetry.lockが固定するバージョンとハッシュによる再現性の担保
pyproject.tomlが「どのバージョン帯を許容するか」を示すのに対し、poetry.lockは「実際にどのバージョンを使うか」を厳密に記録します。ここには、解決された各パッケージの正確なバージョンに加え、配布物のハッシュ値まで保存されます。このハッシュによって、ダウンロードしたファイルが改ざんされていないかも検証できるのです。
poetry.lockが存在する状態で poetry install を実行すると、Poetryは依存を再解決せず、記録どおりのバージョンをそのまま再現します。これにより、開発者のマシン、同僚のマシン、本番サーバーのいずれでも、まったく同じ依存構成が手に入ります。再現性が保証されることは、「自分の環境では動いたのに」という典型的なトラブルを根本から減らしてくれるでしょう。チーム開発において、poetry.lockはまさに環境の共通言語として機能します。ロックファイルを起点に環境をそろえる運用が定着すれば、依存に起因するトラブルは目に見えて減っていくでしょう。
キャレット要件とチルダ要件によるバージョン指定の違いと判断基準
Poetryではバージョン制約を記号で表現でき、なかでもよく使うのがキャレットとチルダです。両者は許容する更新の範囲が異なるため、意図に合わせて選ぶ必要があります。代表的な指定の意味を下の表に整理します。
| 記法 | 意味する範囲 | 許容される更新 |
|---|---|---|
^1.2.3 |
>=1.2.3, <2.0.0 |
マイナー・パッチの更新まで |
~1.2.3 |
>=1.2.3, <1.3.0 |
パッチの更新のみ |
キャレットは、左端のゼロでない桁を変えない範囲で更新を許す指定で、後方互換が保たれる前提のもとで広めに更新を受け入れます。一方チルダは、より狭くパッチレベルの更新だけに絞りたいときに向いています。安定性を最優先するならチルダ、適度に新しい修正を取り込みたいならキャレットという判断基準が目安になるでしょう。なお、キャレットの挙動はゼロを含むバージョンで変わるため、その点だけは公式の定義を確認しておくと安心です。迷ったときは、まずキャレットを基本に据え、安定性をより重視したい依存に対してチルダを選ぶと運用しやすくなります。
開発用依存をgroupで分離するdependency groupsの記法と実務例
テストツールやコード整形ツールのように、開発時だけ必要で本番には不要なパッケージがあります。これらを通常の依存と混ぜてしまうと、本番環境にも余計なものが入り、サイズや安全性の面で好ましくありません。Poetryでは、こうした依存を [tool.poetry.group.dev.dependencies] のようにグループへ分けて管理できます。
開発用の依存を追加するときは poetry add --group dev pytest のように、グループ名を指定します。インストール時に開発用を除きたい場合は poetry install --without dev を使えば、本番に必要な依存だけが入ります。逆に、特定のグループだけを入れたいときは poetry install --only main のように対象を絞る仕組みです。公式の依存管理ドキュメントは、既定でメイングループと非オプショナルの全グループが入ること、そして --without が --with より優先されることを示しています。両方を同時に渡したときに除外が勝つ、という順序は覚えておく価値のある規則です。用途ごとに依存を整理しておけば、本番とローカルで入れるものを的確に切り替えられます。
poetry.lockをコミットすべきかどうかの判断基準とチーム運用
poetry.lockをバージョン管理に含めるべきかは、プロジェクトの性質によって判断が分かれます。結論から言えば、アプリケーション開発では原則としてコミットするのが推奨されます。ロックファイルを共有することで、チーム全員が寸分違わぬ依存構成を再現できるからです。
一方、他者に配布するライブラリを開発している場合は、考え方が少し変わります。ライブラリ側で依存を固定しすぎると、利用者の環境で柔軟にバージョンを選べなくなるためです。アプリならコミットして再現性を守り、ライブラリならpyproject.tomlの制約を中心に据えるという使い分けが基本になるでしょう。チームで運用する際は、poetry.lockを更新した人がその変更を確実に共有し、各自が poetry install で同期する流れを徹底することが大切です。この運用が崩れると、せっかくのロックファイルも効果を発揮しにくくなります。更新は変更内容が明確になるよう、できれば独立した単位で記録しておくとレビューもしやすくなるでしょう。
PEP 621準拠の[project]テーブルへの移行と従来記法の比較
Poetry 2.0からは、Pythonの標準仕様であるPEP 621に準拠した記法が使えるようになりました。これにより、メタデータをPoetry独自の [tool.poetry] ではなく、標準化された [project] テーブルに記述できます。他のツールとも共通の書式になるため、エコシステム全体での相互運用性が高まる点が大きな変化です。
標準記法では、依存を dependencies = ["requests>=2.32"] のようにPEP 508形式の文字列で並べます。一方、従来のPoetry記法では requests = "^2.32" のようにキーと値で記述してきました。新規プロジェクトなら標準の [project] 記法を選ぶのが素直です。ただし全部が移せるわけではありません。公式のpyproject解説によれば、package-mode、packages、include と exclude、そして依存グループの定義はPoetry固有の機能なので [tool.poetry] 側に残ります。ライブラリではなくアプリを作る場合は package-mode = false を置くと、name や version の記述を省いて依存管理だけに使えます。同じ項目を両方の記法で重複設定すると警告が出るので、どちらに寄せるかは先に決めておいてください。
依存パッケージの追加と更新を中心としたpoetryの操作コマンド
Poetryを日常的に使ううえで手が覚えるのは、依存パッケージを追加・更新・削除する一連のコマンドです。これらは似ているようでいて、影響する範囲や使うべき場面が明確に異なります。この章では、現場で頻繁に使う操作コマンドを取り上げ、それぞれの役割と具体的な使い方を整理して解説します。
poetry addによる依存追加とバージョン制約指定の具体例
新しい依存を追加する基本コマンドが poetry add です。たとえば poetry add requests と実行すると、最新の適切なバージョンが選ばれ、pyproject.tomlとpoetry.lockの両方が自動で更新されます。バージョンを意識せずに追加できる手軽さが、このコマンドの大きな利点でしょう。
もちろん、バージョンを明示的に指定することも可能です。範囲を絞りたい場合は poetry add "django>=4.2,<5.0" のように制約を渡せますし、特定の記法を使いたいなら poetry add "requests@^2.32" といった形でも指定できます。追加と同時に依存解決まで行われるため、ほかのパッケージと矛盾する指定はその場でエラーになります。手動でファイルを書き換える方法に比べ、整合性を保ったまま依存を増やせるのが安心な点です。日々の開発では、まずこのコマンドを使いこなすことが第一歩になります。
poetry updateとpoetry installが更新する範囲の明確な違い
初心者が混同しやすいのが poetry update と poetry install の違いです。両者はどちらも依存を環境に反映しますが、poetry.lockに対する扱いがまったく異なります。この違いを理解しておかないと、意図せず依存が更新されてしまう事故につながります。
poetry install は、poetry.lockに記録されたバージョンをそのまま環境へ再現するコマンドです。ロックファイルを書き換えないため、再現性を保ったまま環境を整えられます。これに対し poetry update は、pyproject.tomlの制約の範囲内で依存を最新へと解決し直し、poetry.lock自体を更新します。つまり、環境をそろえたいだけなら poetry install、依存を意図的に新しくしたいなら poetry update という使い分けになるのです。この区別を押さえておけば、不用意な更新による不具合を避けられるでしょう。
poetry removeとpoetry showで行う依存の削除と一覧確認
不要になった依存を取り除くときは poetry remove を使います。たとえば poetry remove requests と実行すれば、そのパッケージがpyproject.tomlとpoetry.lockの両方から削除され、環境からも取り除かれます。手作業でファイルを編集する場合と違い、関連する記述を漏れなく整理してくれるのが利点です。
現在どのような依存が入っているかを確認したいときは poetry show が役立ちます。実行すれば、インストール済みのパッケージとそのバージョンが一覧で表示されるので、いまの状況をひと目で把握できるのです。さらに依存関係のつながりを階層的に見たい場合は poetry show --tree を使うと、どのパッケージがどの下位依存を引き込んでいるかが視覚的に分かります。削除と確認のコマンドを組み合わせれば、依存の全体像を保ちながら無駄のない構成を維持できるでしょう。定期的な棚卸しの習慣も、健全なプロジェクト運営に役立ちます。
開発用依存を–groupオプションで追加する場合の実務的な書き方
前の章で触れたグループ管理は、コマンドからも簡単に扱えます。開発時だけ使うツールを追加したいときに用いるのが --group オプションです。poetry add --group dev pytest のように、--group に続けてグループ名を書けば、指定したパッケージが通常の依存とは別のグループに記録されます。
複数のツールをまとめて加えることもでき、poetry add --group dev black ruff のように並べて書けば一度に追加できます。テスト用、ドキュメント用、整形用といった具合に目的別のグループを設けておくと、後からどれが何のための依存なのかが分かりやすくなるのです。本番には不要なものを明確に切り分けておけば、デプロイ時に余計なパッケージを排除しやすくなります。なお追加したグループを既定でインストール対象から外したい場合は、グループ定義に optional = true を指定しておく方法もあります。グループを意識した追加は、プロジェクトが大きくなるほど効果を発揮するでしょう。整理された依存構成は、チーム全体の見通しのよさにもつながります。
poetry exportでrequirements.txtへ変換する場面と手順
デプロイ先やほかのツールがrequirements.txt形式を前提としている場合、Poetryの依存をその形式へ書き出したくなることがあります。この変換を担うのが poetry export ですが、ここで注意点があります。Poetry 2.0以降では、この機能は既定で同梱されておらず、プラグインとして導入する必要があるのです。
公式CLIリファレンスも「このコマンドはExport Poetry Pluginが提供する。プラグインはPoetry 2.0から既定では同梱されない」と明記しています。まず poetry self add poetry-plugin-export でプラグインを追加してください。その後 poetry export -f requirements.txt --output requirements.txt を実行すると、ロックされた依存がrequirements.txtとして出力されます。本番向けに開発用依存を除きたい場合は --without dev を付けると便利です。なお、こうして書き出したファイルをpipで入れる際は、すでに依存解決が済んでいるため pip install -r requirements.txt --no-deps のように再解決を抑えるのが推奨されます。Poetryでの管理を保ちつつ、外部の仕組みとも橋渡しできるのがこの機能の役割でしょう。
poetry lockによる依存解決とロックファイル更新の判断基準
pyproject.tomlを手で編集して依存を書き換えたとき、その変更をpoetry.lockへ反映する必要があります。このときに使うのが poetry lock です。このコマンドは依存を解決してpoetry.lockを更新しますが、パッケージのインストール自体は行いません。
つまり、ロックファイルだけを先に整えておきたい場面で役立ちます。CIで依存の整合性を検証したいときや、インストールとロック更新を分けて管理したいときに効きます。1.x系にあった --no-update は現行のCLIリファレンスに載っていません。代わりに、既存のロックを無視して作り直す --regenerate が用意されています。なお、pyproject.tomlの記述とロックファイルの内容がずれていないかを確かめる場面でも、このコマンドが起点になります。pyproject.tomlを変更したあとは poetry lock でロックを整え、続けて poetry install で環境へ反映するという流れが基本です。手順を分けて捉えておけば、依存まわりの操作で迷うことが少なくなります。
Poetryとpip・pipenv・uvの比較から導く選定基準
Pythonの依存管理ツールはPoetryだけではなく、pipやpipenv、2024年以降に一気に普及したuvなど複数の選択肢があります。それぞれに得意な領域があり、プロジェクトの性質によって妥当な答えは一様ではありません。この章では、主要なツールを比較し、どのような基準で選べばよいのかを整理して解説します。
pipとの比較で見えるロックファイル機能と依存解決の明確な差
pipはPythonに標準で付属する、最も基本的なパッケージ管理ツールです。手軽さでは群を抜いていますが、Poetryと比べると依存管理の仕組みには明確な差があります。最大の違いは、解決結果を厳密に記録するロックファイルを標準では持たない点です。
pip単体でも個々のパッケージはインストールできますが、依存全体の整合性を保ったまま記録・再現する機能は弱いままです。一方Poetryは、依存を一括で解決し、その結果をpoetry.lockに固定することで高い再現性を実現します。たとえば同じpoetry.lockがあれば、別のマシンでもほぼ同じ依存構成を再構築できます。pipはシンプルな用途や学習の入り口として優れている反面、規模が大きくなるほど手作業での管理コストが増えていくでしょう。チームでの再現性を重視するなら、Poetryのような専用ツールに分があります。用途の規模に応じて選ぶことが、無理のない選択につながるのです。
pipenvと比較した際の速度・保守状況・機能面での3つの違い
pipenvもPipfileとロックファイルによる依存管理を提供する点で、Poetryと方向性が似ています。ただし、実際に使ううえでは無視できない違いがあるのも事実です。主な相違点を3つの観点から整理します。
- 速度の観点では、pipenvの依存解決は重くなりがちで、規模が大きいプロジェクトほど時間がかかると指摘されることがある
- 保守の観点では、pipenvは開発ペースに波がある時期もあり、活発さの面でPoetryとの差が話題になってきた
- 機能の観点では、pipenvが依存管理に特化するのに対し、Poetryはビルドや公開まで一貫して扱える幅広さを備える
これらを踏まえると、純粋な依存管理だけで足りるならpipenvでも十分ですが、パッケージのビルドや公開まで視野に入れるならPoetryが扱いやすいでしょう。どちらを選ぶにせよ、プロジェクトの将来像を見据えて判断することが大切です。機能の幅と保守の安定性は、長く使うほど効いてくる要素になります。
uvとの比較で問われる実行速度とエコシステム成熟度の判断基準
Rust製のuvは、2024年の公開から短期間で利用者を増やしました。最大の特徴は処理速度で、依存解決やインストールがPoetryより大幅に速いと評価されています。uvの公式ドキュメントによる位置づけは、pip・pip-tools・pipx・poetry・pyenv・virtualenvを置き換える単一ツールです。置き換えられる側のpyenvが何を担っているかはpyenvでPythonのバージョンを切り替える手順で整理しています。大規模な依存を扱う場面ほど、この速度差は体感しやすくなります。uv側の機能や導入手順はuvの環境構築とパッケージ管理の解説で扱っています。
一方で、判断にあたってはエコシステムの成熟度も見逃せません。Poetryは長年使われてきた実績があり、情報や周辺ツールが豊富にそろっています。トラブルが起きた際も、過去の事例や解説記事を見つけやすいのは大きな安心材料でしょう。uvは勢いがある反面、比較的新しいツールであるため、長期運用での知見はこれから蓄積されていく段階にあります。プラグインやエディタとの連携といった周辺環境の厚みという点でも、現時点ではPoetryに一日の長があるといえるでしょう。速度を最優先するならuv、安定した実績と豊富な情報を重視するならPoetryという軸で選んでください。判断を1つ言い切ります。既存のPoetryプロジェクトを、速度だけを理由にuvへ移すのは見送るべきです。CIの待ち時間が数十秒縮む代わりに、社内手順書とDockerfileとCI定義の全部を書き換える工数が乗ります。移す価値があるのは、依存が数百規模でCIが恒常的に詰まっている場合か、新規に立ち上げる場合に限られます。
condaとの使い分けで重要になる科学計算・データ分析の観点
condaはPoetryやpipとは少し性格の異なるツールで、Pythonのパッケージだけでなく、C言語のライブラリなどPython以外の依存もまとめて扱えます。pip側との使い分けはpipとcondaの違いと商用ライセンスの解説で詳しく整理しています。この特性が大きく生きるのが、科学計算やデータ分析の領域です。数値計算ライブラリのように、裏側でネイティブなライブラリに依存するパッケージを扱う際に強みを発揮します。
一般的なWebアプリケーション開発やライブラリ配布であれば、Poetryのほうが軽快で標準的な選択になりやすいでしょう。一方、複雑なネイティブ依存を抱える研究用途やデータ分析の現場では、condaの守備範囲の広さが頼りになります。とりわけGPUを使う機械学習環境のように、Python以外の構成要素が多い場面ではその違いが顕著です。両者は競合するというより、扱う対象によって使い分けるものだと捉えるのが実態に近いといえます。自分のプロジェクトがどちらの領域に属するかを見極めることが、妥当な選択の出発点になります。
主要4ツールの機能と適性を一覧で整理した選定の比較観点と基準
ここまで個別に見てきた4つのツールを、横断的に比較してみましょう。それぞれの特徴を一覧にすると、どの場面でどれを選ぶべきかが整理しやすくなります。下の表に主要な観点をまとめます。
| ツール | ロックファイル | 速度の傾向 | 主な特徴・用途 |
|---|---|---|---|
| pip | 標準では持たない | 軽量で手軽 | 導入と学習の入口向け |
| Poetry | poetry.lock を持つ | 標準的 | 依存管理からビルド・公開まで一貫 |
| pipenv | Pipfile.lock を持つ | やや重い傾向 | 依存管理に特化 |
| uv | ロックに対応 | 非常に高速 | 速度重視の新興ツール |
この表からも分かるとおり、手軽さならpip、総合力ならPoetry、速度ならuvという大まかな住み分けが見えてきます。ただし表はあくまで傾向で、実際の選定では自分のプロジェクトの要件と照らし合わせる作業が要ります。複数の観点を天秤にかけたうえで、もっとも負担が少ない選択を採るのが現実的な進め方です。一覧で全体像をつかんでおくと、判断の軸がぶれにくくなります。
プロジェクト規模とチーム体制の観点から導くツール選定の判断基準
最終的にどのツールを選ぶかは、機能の優劣だけでなく、プロジェクトの規模やチームの体制によって決まります。小さな個人プロジェクトと、多人数で長期運用する大規模プロジェクトとでは、重視すべき点が変わってくるからです。判断の目安を整理しておきましょう。
個人で素早く試したいだけなら、標準で使えるpipや高速なuvが向いています。複数人で開発し、再現性とビルド・公開までを一貫して管理したいならPoetryが頼りになるでしょう。チームの習熟度も重要な要素で、すでに特定のツールに慣れているなら、その資産を活かす選択も十分に合理的です。新しく学ぶコストと得られる利点を比べたうえで、移行するかどうかを判断するのが現実的な進め方になります。導入後の運用ルールをチーム全体で共有できるかどうかも、定着を左右する見落としやすい論点だといえます。大切なのは、流行ではなく自分たちの状況に合うかどうかで決めることです。規模と体制という視点を持てば、後悔の少ない選定にたどり着けます。
Poetryのメリットとデメリットを踏まえた実務での導入判断基準
Poetryの導入を検討するうえでは、得られる利点だけでなく、無視できない弱点も含めた全体像が要ります。どんなツールにも向き不向きがあり、現場の状況によって評価は変わるものです。この章では、Poetryのメリットとデメリットを整理し、どのような場合に導入すべきかという判断の軸を解説します。
依存解決の厳密さと環境再現性がもたらす開発体験上の3つの利点
Poetryを使う最大の魅力は、依存解決の厳密さと環境再現性がもたらす安定した開発体験にあります。手作業による管理ではどうしても生じがちな「動かない」「環境が違う」といった問題を、仕組みの力で抑え込めるのが強みです。ここでは、その恩恵を代表的な3つの利点に整理してみましょう。
- 依存全体を一括で解決するため、互いに矛盾するバージョンの組み合わせを未然に防げる
- poetry.lockによって解決結果が固定され、別の環境でも同じ依存構成を正確に再現できる
- pyproject.tomlに設定が集約され、依存とプロジェクト情報を一か所で見通せる
これらが組み合わさることで、開発者は依存の不整合に悩まされる時間を減らし、本来の実装に集中しやすくなります。とくに複数人で開発する場面では、全員の環境がそろう安心感は大きいものです。仕組みに任せられる部分を任せてしまうことが、結果として開発全体の速度を底上げしてくれるでしょう。
依存解決が遅いというデメリットと2.x系での改善状況の実態評価
一方で、Poetryには弱点も存在します。よく挙げられるのが、依存解決にかかる時間です。多数のパッケージを扱う大規模なプロジェクトでは、解決処理に時間がかかり、待たされる場面があると指摘されてきました。
ただし、この点については継続的な改善が進められてきた経緯があります。バージョンを重ねるなかで依存解決やインストールの処理は見直され、以前より快適に使える場面が増えてきました。とくに依存の数が限られた一般的なプロジェクトであれば、待ち時間が深刻な問題になる場面はそれほど多くないでしょう。多くの依存を一度にすべて解決し直すような重い操作でなければ、日常的な使用感はおおむね良好だと感じられるはずです。とはいえ、Rust製のuvのような新興ツールと比べると、速度面ではなお差があるのも事実です。速度を最重視する用途では、この特性を理解したうえで選ぶ必要があるでしょう。弱点を正しく把握しておけば、過度な期待による失望を避けられます。
PoetryのビルドバックエンドとPyPI公開を一元化できる強み
Poetryの見逃せない強みのひとつが、依存管理だけにとどまらず、パッケージのビルドから公開までを一貫して扱える点です。ライブラリを開発して配布する場面では、この一元化が大きな効率につながります。複数のツールを使い分ける手間を省けるのは、地味ながら効いてくる利点でしょう。
poetry build を実行すれば、配布用のパッケージ形式であるwheelとsdistがまとめて生成されます。続けて poetry publish を使えば、生成した成果物をPyPIへアップロードできます。なお、Poetry 2.1以降ではビルドの仕組みが見直され、pyproject.tomlの記述に応じて別のビルドバックエンドを選ぶ柔軟さも加わりました。依存管理と公開作業が同じ設定ファイルの上で完結するため、リリースまでの流れがすっきりと整理されるのです。ライブラリ作者にとっては、これだけでも導入する価値が十分にあるといえます。
学習コストの高さとチーム浸透の難しさという導入時の失敗パターン
利点が多いPoetryですが、導入時にはつまずきやすい落とし穴もあります。代表的なのが、学習コストの高さです。pipに慣れた開発者にとっては、概念やコマンド体系が新しく、最初のうちは戸惑いを感じることが少なくありません。
とくにチーム全体へ浸透させようとする場面では、この壁が顕在化しやすくなります。一部のメンバーだけがPoetryを使い、ほかはpipのまま、といった状態になると、かえって運用が混乱しかねません。こうした分断は依存の食い違いという形で表面化し、せっかくの再現性という利点を打ち消してしまうこともあるのです。導入を成功させるには、短い手順書を用意し、最初の設定を担当者がまとめて行う段取りが要ります。ツールの優秀さだけに頼らず、人への定着まで見据えてください。失敗例の多くは、技術そのものではなく浸透の設計を軽視したところから生まれます。導入の旗振り役を一人決めておくだけでも、定着の成否は大きく変わるものです。社内に旗振り役を置けない、あるいはCIとデプロイまで含めた土台ごと整えたい場合は、保守運用・内製化支援のように外部の手を借りて初期設定と運用ルールを固めてしまうほうが、結局は速く片付きます。
既存のpip運用から移行する際のコストと効果のバランス判断基準
すでにpipで運用しているプロジェクトにPoetryを導入すべきかは、移行にかかるコストと得られる効果を天秤にかけて判断します。移行は一瞬で終わるものではなく、依存の棚卸しや設定ファイルの整備といった作業が伴うからです。この手間を上回る効果が見込めるかどうかが、判断の分かれ目になります。
効果が大きいのは、依存の数が多く、再現性の確保に苦労しているようなプロジェクトです。こうした現場では、ロックファイルによる恩恵がコストを十分に上回るでしょう。逆に、依存がごくわずかで、短期間で役目を終えるスクリプトのような用途なら、無理に移行する必要は薄いかもしれません。得られる効果が小さい場面で手間だけをかけるのは、合理的とはいえないからです。移行を決めたら、既存のrequirements.txtをもとに依存を洗い出し、段階的に置き換えていくのが安全な進め方です。コストと効果を冷静に見比べることが、後悔のない判断につながります。
個人開発・小規模・大規模チームそれぞれに適した導入可否の目安
最後に、プロジェクトの規模や開発体制ごとに、Poetryを導入すべきかどうかの目安を整理しておきましょう。一律に「使うべき」と言えるものではなく、状況に応じた判断が現実的です。ここでは個人開発、小規模チーム、大規模チームの3つに分けて考えてみます。
個人開発で手軽さを最優先するなら、必ずしもPoetryである必要はなく、軽量な選択肢でも十分なことがあります。小規模チームでは、環境をそろえる効果が出始めるため、導入する価値が見えてきやすいでしょう。そして大規模チームや長期運用のプロジェクトでは、再現性とビルド・公開の一元化という強みが最も生きてきます。人の入れ替わりがあっても同じ環境を保てることは、長く続く開発ほど重みを増す利点だといえるでしょう。規模が大きくなるほど、Poetryの仕組みがもたらす安定性の恩恵は増していくのです。自分たちがどの段階にいるかを見極めることが、過不足のない導入判断への近道になります。
PoetryのCI/CD連携とDockerイメージ分離で使う実装手順
Poetryは開発環境だけでなく、CI/CDパイプラインやDockerと組み合わせたときに効き目が大きくなります。自動化された環境で依存を確実に再現できれば、デプロイの信頼性が目に見えて上がる仕組みです。この章では、実務でよく使われる統合のパターンを、そのまま貼れる設定ファイルとともに紹介します。パイプラインそのものの考え方はCI/CDの仕組みと導入判断の解説を参照してください。
GitHub Actionsでpoetry.lockをキーにキャッシュする設定例
GitHub ActionsでPoetryを使う場合、毎回ゼロから依存をインストールしていると、ビルド時間が無駄に長くなりがちです。そこで効くのが依存のキャッシュです。一度解決した依存を保存し、次回以降に再利用すれば、実行時間を大きく削れます。
骨格は次のとおりです。actions/setup-python でPythonを準備し、仮想環境をプロジェクト直下に固定したうえで、poetry.lock のハッシュをキャッシュキーにします。そのまま .github/workflows/test.yml として置ける形にしてあります。
name: test
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
with:
python-version: "3.12"
- run: pipx install poetry==2.4.3
- run: poetry config virtualenvs.in-project true
- uses: actions/cache@v6
with:
path: .venv
key: venv-${{ runner.os }}-${{ hashFiles('poetry.lock') }}
- run: poetry check --lock
- run: poetry install --no-root
- run: poetry run pytestPoetry本体の版を poetry==2.4.3 と固定している点が肝です。固定しないと、ある日Poetry側の更新でロック形式が変わり、手元では通るのにCIだけ落ちる状態が起きます。キャッシュキーの設計や復元されないときの切り分けを扱うのが、actions/cacheのkey設計をまとめた解説です。依存に変更がない通常のプッシュなら、キャッシュから環境が復元されるので待ち時間はほぼ消えます。
Dockerマルチステージビルドで依存層を分離する軽量化の手順
Dockerイメージを軽量かつ安全に保つうえで効くのが、マルチステージビルドです。依存をインストールする工程と、実際にアプリを動かす工程を分ければ、最終的なイメージに不要なものを持ち込まずに済みます。Poetryと組み合わせる際の基本的な流れを、手順として整理します。
- ビルド用ステージでPoetryを導入し、pyproject.tomlとpoetry.lockをコピーして依存をインストールする
- 依存を仮想環境やwheelとしてまとめ、アプリのコードもこの段階で取り込む
- 実行用ステージには必要な成果物だけを移し、Poetry本体やビルド用の道具は持ち込まない
コードにすると次のようになります。virtualenvs.in-project を有効にして .venv をビルド段で作り、実行段にはそのディレクトリだけを移す構成です。
FROM python:3.12-slim AS builder
ENV POETRY_VIRTUALENVS_IN_PROJECT=true
RUN pip install --no-cache-dir poetry==2.4.3
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --without dev
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "src.main"]依存ファイルだけを先にCOPYしている理由は、レイヤーキャッシュです。アプリのソースだけが変わったビルドでは poetry install の層が再利用され、再ビルドが数秒で終わります。命令ごとの意味と書き分けはDockerfileの書き方の解説にまとめました。この分離によって、最終イメージにはアプリの実行に必要なものだけが残り、サイズと攻撃対象を同時に小さくできます。
poetry install –no-rootを使う場面とCI高速化の判断基準
CIでテストを走らせるだけの場面では、プロジェクト自身をパッケージとしてインストールする必要がないことがあります。そんなときに役立つのが --no-root オプションです。poetry install --no-root と実行すると、依存だけをインストールし、プロジェクト本体のインストールは省略します。
この指定によって、不要なビルド処理が省かれ、CIの実行が少し速くなります。とくにライブラリではなくアプリケーションを開発している場合、自分自身をインストールする意味は薄いため、この省略が理にかなうのです。一方で、プロジェクトをパッケージとして実際にインポートしてテストするような構成では、本体のインストールが必要になる場面もあります。つまり、テストの中身に応じて付けるかどうかを見極めることが判断の基準になるでしょう。むやみに付けるのではなく、何をテストしたいのかから逆算するのが堅実です。CIの目的が明確であれば、付けるべきかどうかは自然と定まってくるはずです。
requirements.txt出力を併用したDockerイメージ軽量化の手順
Dockerイメージをさらに軽くしたい場合、Poetry本体をイメージに含めず、requirements.txtだけを使って依存をインストールする方法があります。ビルド段階でPoetryから依存を書き出し、実行イメージにはpipだけで入れるという発想です。Poetry自体の重さをイメージから切り離せるのが、この手法の狙いになります。
前提として、Poetry 2.0以降では poetry export がプラグイン扱いになっているため、poetry self add poetry-plugin-export で導入しておきます。そのうえでビルド用ステージにて poetry export -f requirements.txt --output requirements.txt --without dev のように出力すれば、本番向けの依存一覧を書き出せるはずです。実行イメージでは pip install -r requirements.txt --no-deps で入れると、すでに解決済みの依存をそのまま再現できます。Poetryを含めない分だけイメージは小さくなり、起動も軽快になるでしょう。軽量化を突き詰めたい場面で、覚えておくと役立つ手法です。
CIでのpoetry.lock検証によるバージョン固定漏れの防止策
CIに組み込んでおくと安心なのが、poetry.lockが最新の状態に保たれているかの検証です。pyproject.tomlを変更したのにロックファイルの更新を忘れると、環境ごとに異なる依存が入り込む危険があります。こうした固定漏れを自動で検出できれば、再現性を守る大きな助けになります。
具体的には、CIのなかで poetry check --lock を実行します。poetry check はpyproject.tomlとpoetry.lockの整合性を検証するコマンドで、--lock を付けるとロックファイルの存在確認も加わるのです。もし両者の内容がずれていれば、このチェックが失敗としてエラーを返してくれます。これにより、ロック更新の忘れを人手のレビューに頼らず、機械的に止められるのです。あわせて poetry install がロックファイルどおりに通るかも確認しておけば、依存まわりの事故はかなり防げるでしょう。仕組みで漏れを塞いでおくことが、安定したリリースの土台になります。レビュー担当者の負担も軽くなり、本質的な確認に時間を割けるようになるでしょう。
本番環境で開発用依存を除外する–without指定の実務例
本番環境にデプロイする際は、テストや整形に使う開発用の依存まで一緒に入れてしまうと、無駄が増えるうえにリスクも広がります。そこで使うのが、特定のグループを除外する --without オプションです。本番に不要な依存をインストール段階で切り落とせるのが、この指定の目的になります。
たとえば開発用の依存をdevグループにまとめてある場合、poetry install --without dev と実行すれば、そのグループを除いた本番向けの依存だけが入ります。逆に、特定のグループだけを対象にしたいときは --only を使うという選択肢もあります。こうしてインストールの範囲を明確に絞っておくと、本番イメージが軽くなるだけでなく、想定外のパッケージが紛れ込む余地も減らせるのです。開発と本番で入れるものを意図的に分ける姿勢は、安全な運用の基本といえるでしょう。グループ機能と組み合わせれば、環境ごとの依存管理がぐっと扱いやすくなります。
Poetry 2.1以降で加わった仕様とpylock.toml書き出しの実務
2.0の変更点は日本語の情報も増えましたが、その後の2.1から2.4までに入った仕様はまだ薄いままです。ここでは公式のリリース履歴とCLIリファレンスをもとに、実務で影響が出る4点を取り上げます。いずれも1.x系や2.0時点の手順書をそのまま使っていると気づけない箇所になります。
2.1と2.2で加わったbuildコマンドとPython管理の変更点
2.1.0は2025年2月15日に公開されました。ここで入ったのが、ビルドシステムに依存しない build コマンドと、実験的なPython管理コマンドです。前者はpoetry-core以外のビルドバックエンドを指定したプロジェクトでも poetry build を通せるようにするもので、[build-system] の記述を書き換えずにビルド手段を揃えられます。
後者は、Python本体の導入までPoetry側が面倒を見る系統のコマンドです。実験的な位置づけなので、本番のCIで頼り切るのは早いと考えてください。CIでは actions/setup-python のような既存の仕組みでPythonを固定し、Poetryには依存解決だけを任せるほうが、失敗したときの切り分けが楽になります。2.2系は2025年9月に出ており、こちらは細かな修正が中心でした。
PEP 735記法とtool.poetry.groupを併存させる書き方
開発用依存の書き方は現在2通りあります。従来の [tool.poetry.group.test.dependencies] と、Python標準側で定まった [dependency-groups] です。公式の依存管理ドキュメントは両方の記法を並べて示しており、後者ではPEP 508形式の文字列を並べる形になります。実際のpyproject.tomlは次のようになります。
[project]
name = "sample-app"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
"requests (>=2.32,<3.0)",
]
[dependency-groups]
dev = [
"pytest (>=8.0,<9.0)",
"ruff",
]
[tool.poetry.requires-plugins]
poetry-plugin-export = ">=1.8"
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"オプショナル指定だけは注意が要ります。[dependency-groups] で書いたグループを既定のインストール対象から外したい場合でも、optional = true は [tool.poetry.group.docs] 側に置く形が公式の例です。つまり両方のテーブルが同時に登場します。新規プロジェクトなら標準側の [dependency-groups] に寄せ、Poetry固有の設定だけを [tool.poetry] に残す構成が見通しよく収まります。
PEP 751のpylock.toml書き出しと従来形式の使い分け
2026年1月18日公開の2.3.0で、pylock.toml形式の書き出しに対応しました。pylock.tomlはPEP 751で定められた、ツールに依存しないロックファイル形式です。これまでロックファイルはpoetry.lockやPipfile.lockのようにツールごとに分かれており、他ツールへ渡すにはrequirements.txtへ落とす以外の道がありませんでした。
書き出し自体はpoetry-plugin-export側の機能なので、先にプラグインを入れる手順は従来と変わりません。使い分けの判断は単純です。渡し先がpylock.tomlを読めるならそちらを、読めないならrequirements.txtを選びます。2026年9月時点では消費側の対応がまだ限られるため、Dockerの実行イメージへ依存を渡す用途では引き続きrequirements.txtが無難でしょう。標準形式の対応が広がってから切り替える、という順番で構いません。
requires-poetryとrequires-pluginsで版を固定する運用
Poetry本体とプラグインの版がメンバー間でずれると、同じpyproject.tomlから違う結果が出ます。2.0以降は、この要件をpyproject.toml側で宣言できるようになりました。[tool.poetry] の requires-poetry に対応する版の範囲を書き、[tool.poetry.requires-plugins] に必要なプラグインと版を書く形です。
公式のCLIリファレンスは、export機能を使い続ける場合の書き方として poetry-plugin-export = ">=1.8" を挙げています。宣言しておけば、プラグインが入っていない環境で操作したときに気づけます。手順書に「各自でプラグインを追加すること」と書くだけの運用より、リポジトリに宣言を置くほうが確実です。CIでも同じ宣言が効くため、ローカルとCIの差分はここでかなり詰められます。
よくある質問
Poetryについて検索されている質問のうち、導入判断に直結する5つに答えます。
Poetryとpipはどちらを使うべきですか？
依存の数とチームの人数で決めてください。依存が数個で自分だけが触るスクリプトなら、標準のvenvとpipで足ります。依存が数十を超える、あるいは複数人で同じ環境を再現したい段階に入ったら、ロックファイルを持つPoetryに分があります。pipにもハッシュ付きファイルによる固定手段はありますが、そのファイルを人手で保ち続ける運用が要り、抜け漏れが起きやすいのが実情です。分かれ目は「同じ環境を他人が再現する必要があるか」の一点に集約されます。
poetry shellが使えなくなったのはなぜですか？
Poetry 2.0でコア機能から外れ、poetry-plugin-shellという別プラグインへ移されたためです。標準の代替は poetry env activate ですが、これは環境を有効化するのではなく有効化用のコマンドを表示するだけだと、公式のCLIリファレンスが明記しています。表示された行をシェルで評価して、はじめて環境に入れる仕組みです。従来と同じ操作感を保ちたいなら、poetry self add poetry-plugin-shell でプラグインを入れ直す道もあります。
poetry.lockはGitにコミットすべきですか？
アプリケーションならコミットします。全員と本番が同じバージョンを再現できることが、ロックファイルを持つ理由そのものだからです。逆に、他者へ配布するライブラリでは、pyproject.toml側の制約を主役に据えます。ライブラリが依存を固定しすぎると、利用者側の解決を縛ってしまうためです。なお、コミットしたうえでCIに poetry check --lock を置き、pyproject.tomlとの食い違いを機械的に止めるところまでやって、はじめて効果が出ます。
Poetryとuvは併用できますか？
同じプロジェクトで両方をロック管理に使うのは避けてください。poetry.lockとuv.lockが並ぶと、どちらが正なのか判断できなくなります。現実的な併用は、プロジェクトの依存管理はPoetryに据えたまま、uvはコマンドラインツールの実行や検証用の使い捨て環境に限る形です。移行を検討する場合も、まず新規プロジェクトで試し、既存プロジェクトはCIが恒常的に詰まっているときに限って動かすのが安全でしょう。
Poetryの導入にはどのPythonバージョンが必要ですか？
公式のインストールドキュメントは、Poetry本体の動作要件をPython 3.10以上と示しています。2.0の時点で3.8のサポートが切れて3.9以上になり、その後3.10以上まで上がりました。ここで押さえておきたいのは、Poetryを動かすPythonと、プロジェクトが使うPythonが別物だという点になります。pipxや公式インストーラでPoetryを隔離しておけば、プロジェクト側は poetry env use で任意のバージョンを指定できます。古いPythonを対象にした開発でも、Poetry本体さえ新しい環境で動けば支障はありません。
関連記事
- uvとは？Pythonの環境構築・パッケージ管理・バージョン管理の使い方：Poetryの比較対象として最有力のツール。速度と機能範囲の実像を確認できます。
- pipとcondaの違いと使い分け：科学計算・データ分析でcondaを選ぶ場面の線引きを詳しく扱っています。
- 仮想環境とは？venv・コンテナ・仮想マシンの違い：Poetryが作る仮想環境がどの隔離レベルにあたるかを整理しています。
- GitHub Actionsのキャッシュとkey設計：本文のCI設定例で使ったキャッシュキーの決め方を掘り下げています。
- Dockerfileとは｜書き方・主要命令・ベストプラクティス：マルチステージビルドの記述をさらに詰めたい場合の参考になります。
