これまでpyenvとvenvで生きてきたのだが、プロジェクト事情でpoetryを使うことになり、まとめて調査したのでメモ。
概要
仮想環境の管理（venv関連コマンドの代わり）とパッケージ管理（pipの代わり）をやってくれる、それなりにモダンなやり方。（最新とは言っていない）
Pythonのバージョン管理（pyenv相当）は範疇外なので、pyenvやmiseと併用する。
使い方
pyenv
pyenvとは共存できるので、このあたりは従来と一緒。
% pyenv install 3.13.9
% cd <プロジェクトルート>
% pyenv local 3.13.9 # これで現在の使用バージョンを選択。また。.python-version が作成/更新され、以降、このルート配下ではpyenv localが不要になる
仮想環境の有効化とパッケージ管理
venvやpip + requirements.txtからpoetryに変わる。
従来：
% python -m venv .venv # 仮想環境の作成
% source .venv/bin/activate # 仮想環境の有効化
% pip install -r requirements.txt # 依存関係のインストール
% deactivate # 終了
今後：
% poetry init # tomlファイルの作成
% poetry env use python # 仮想環境の作成
% # poetry shell # 仮想環境の有効化。2.0では非推奨、かつ不要
% poetry install # 依存関係のインストール
% exit # 終了
環境の確認は以下のコマンドで行う。
% poetry env info
追加パッケージの個別導入
仮想環境で追加のパッケージを個別導入したい場合の例。
pipは使わない点がポイント。
従来：
% pip install boto3
今後：
% poetry add boto3
プログラムの実行
「poetry管理の仮想環境内で実行」されていることが保証されるよう、poetry runを頭に付ける。
仮想環境の有効化（poetry shell）を仮に忘れていても、ちゃんとリカバーしてくれる（要は、忘れてたらpoetry shell相当のことを代わりにやってくれる）。
※poetry shellはdeprecated。基本的に、シェルには入らず、実行時に指定するのが推奨となっている模様。
streamlitを例にとると、以下のようになる。
従来：
% streamlit run app.py
今後：
% poetry run streamlit run app.py
CIで実行する場合も一緒。
注意点
- インストール直後に、venvディレクトリ（
.venv）の作成先をプロジェクトルートに設定しておく。
% poetry config virtualenvs.in-project true
% poetry config --list | grep virtualenvs.in-project
デフォルトではfalseとなっており、~/.cache/pypoetry配下に作られてしまうのでわかりづらくなる。
従来のようにプロジェクトルートにvenv（相当の）ディレクトリを作りたければtrue推奨。
- 初回はプロジェクトルートで初期化だけ必要。
% poetry init
これでpyproject.toml（requirements.txtに相当）とpoetry.lock（tomlで指定された依存関係の決定結果。編集無用）が作成される。
- 既存のrequirements.txtがある場合。
poetry add $(cat requirements.txt) で取り込むことができる。
ただし、これを使うと[project.dependencies]の形式（PEP621形式）になるようなので、素直に個別追加するかtomlを直接編集して[tool.poetry.dependencies]の形式（poetry形式）で追加する方が、矛盾が起きにくい。
- poetry shellは非推奨、廃止予定。
やろうと思えば以下で代替できるが、面倒なのでプログラムのテスト時にpoetry runを頭に付けることで自動的に仮想環境を使わせる方が実務上はベター。
% poetry env activate
% source (表示されたディレクトリ)/.venv/bin/activate
ちなみに、pipの感覚だとpoetry installの前に仮想環境を有効化しておきたい気持ちになるが、実はpoetryでは依存関係のインストールは仮想環境の有効化とは独立しており、.venvをpoetry install実施時に内部的に特定してフルパスで使ってくれるので、事前に仮想環境の有効化は不要（仮想環境を有効化していない状態でpoetry installしても、依存関係は仮想環境下にインストールされる。pipの時は違った）
このあたりがpoetryの本質というかうまみでもある（いちいちアクティベートしなくてよい、アクティベート忘れても大丈夫、CIでもよしなに処理）。
| pip/venv | poetry | |
|---|---|---|
| 依存関係のインストール | アクティベート後 | アクティベート不要（poetry installで内部的に処理） |
| プログラムの実行 | アクティベート後 | アクティベート不要（poetry runを頭に付けることで内部的に処理） |
- tomlファイル（依存関係設定）を設定する。
インタラクティブに追加もできるし、poetry add boto3 pandas streamlitのように、コマンドで追加もできる。また、poetry add $(cat requirements.txt) として既存のrequirement.txtから読み取るやり方を取ることもできる。
いずれにせよ、一度addすればtomlファイルに書き込まれる。
また、addはインストールまで併せて実行してくれる（poetry installを内包する）。
- package-modeを無効化しておく。
デフォルトでは、プロジェクト自体もpythonパッケージとしてインストールしようとする挙動をする（パッケージ化）。このため、poetry installがREADME.mdとかを要求してくる。
poetry install --no-rootでひとまず回避可能だが、もしライブラリとして配布する予定がないなら、pytproject.tomlを以下のように変更するのがよい。
name = "my-streamlit-tests"
version = "0.1.0"
package-mode = false
- 既に.venvがあって、作り直したい場合。
% rm -rf venv
% poetry init
% poetry env use python
% poetry add $(cat requirements.txt) # requirements.txtの内容をtomlファイルに反映し、その後インストール
% poetry install
- poetryで作った仮想環境を作り直したい場合。
% poetry env remove # 仮想環境（.venv）とその中の依存関係をアンインストール
% poetry env use python
...
次の一歩
uvはpoetryをさらに高速実装したもので、最近は利用が増えている。MCP Serverの多くでは、これを使って依存関係のインストールをさせたりしている。
が、実務ではpip/venvないしpoetryがまだまだ現役なので、まずはpoetryに慣れて仮想環境とそのうまみ/つらみの肌感覚を養っておくのがよさそう。