PythonのPoetryの使い方メモ

今までPythonの環境構築はpyenv+venvで行っていました。

Pytonのパッケージ管理ツールはいくつかあるのですが、混沌としていて今まで手を出してきませんでした。

そんな中、Poetryを使う機会があったので、せっかくなので一通り触ってみて簡単に使い方をここにまとめておこうと思います。

パッケージ管理ツールのおさらい

今までpyenv+venv一択で使用してきて、パッケージ管理ツールの意味をあまり意識することが無かったので、一旦パッケージ管理ツールの必要性や構成をまとめてみます。

必要性

パッケージにはPythonのバージョンや他のパッケージのバージョンの依存関係があり、それらが一致しないと動作しません。

インストールされているPythonに全てのパッケージをインストールするのではなく、使うPythonのバージョンやパッケージおよび、パッケージのバージョンをプログラム毎に閉じて管理したいです。

そういったプログラムに閉じた環境を構築管理するのが、パッケージ管理ツールの目的です。

構成

パッケージ管理ツールは「Pythonのバージョン管理」「仮想環境」「パッケージのバージョン管理」の積み上げで構成されていて、pyenv+venvの場合は下記のツールで行われています。

Pythonのバージョン管理
- pyenv
- どのバージョンのPythonを使うかを指定する
仮想環境
- venv
- 他のプログラムでインストールしたパッケージが混ざらないよう、そのプログラムに閉じた仮想環境を用意する。
パッケージのバージョン管理
- pip
- pip freeze > requirements.txtで仮想環境にインストールされているパッケージの一覧とバージョンを出力し、pip install -r requirements.txtで復元する

それぞれ別のツールなので、ユーザーがそれぞれの状態を常に意識しながら自分で保守する必要があります。

その作業が手間なので、ツールとして自動化してくれるのが、パッケージ管理ツールです。

以上を踏まえて、Poetryの使い方を見ていきます。

インストール

公式サイトに記載の方法。変わる可能性があるので実際にインストールする時に確認した方がいいです。

curl -sSL https://install.python-poetry.org | python3 -

プロジェクト作成

poetry new <project_name>

<porject_name>のディレクトリが作成され、その中に下記のファイル一式が作成されます。

├── README.md
├── pyproject.toml
├── src
│   └── <project_name>
│       └── __init__.py
└── tests
    └── __init__.py

pyproject.tomlがPoetryの設定ファイルで、パッケージをインストールすると、インストールしたパッケージとバージョンがこのファイルに記載されていきます。

Pythonのバージョンは、プロジェクトを作成した時点のカレントのPythonのバージョンで設定されます。pyproject.tomlを編集することにより、後からバージョンを変更することもできます。

プログラム実行

実行

プロジェクトディレクトリ直下に<python_code.py>コードを置いて実行する場合下記になります。

poetry run python <python_code.py>

runはその後に続くコマンドを実行します。Pythonプログラムだけでなく、Python以外の任意のコマンドも実行できます。

Pythonコマンドを実行した場合、Python仮想環境に入り、その中でPythonプログラムが実行され、プログラムの実行が終わると自動でPython仮想環境から抜けます。

PoetryのPython仮想環境はvenvではなくvirtualenvによって作成されます。

注意

PoetryにはPythonのバージョン管理機能はなく、PythonのバージョンはPoetryのコマンドを実行した時のカレントのPythonのバージョンが適用されます。

Pythonのバージョン管理は、pyenv等を使用して、Poetry外部で行う必要があります。

pyproject.tomlにはPythonのバージョンを指定できる項目があり、プログラム実行時のPythonのバージョンが設定と一致しない時、エラーが表示され実行されません。

それによって、PoetryでPythonのバージョンの制御ができるようになっています。

パッケージ

パッケージインストール

poetry add <package_name>

pyproject.tomlにインストールしたパッケージとバージョンが記録されます。

パッケージアンインストール

poetry remove <packege_name>

全てのパッケージをインストール

poetry install

pyproject.tomlに記載されたパッケージを全てインストールします。

poetry.lockファイル

パッケージをインストールすると、プロジェクトディレクトリ直下にpoetry.lockファイルが作成されます。

このファイルには依存関係を含む、インストールされたパッケージと厳密なバージョン情報が記録されます。

poetry installではこの情報に基づいてパッケージをインストールするので、現在の環境と全く同じものを復元することができます。

パッケージ（dev環境）

本番プログラムでは使用しないが、開発時に使うパッケージをインストールしたい時があります。

Poetryではグループを使って、メインとは区別してインストールを行います。

インストール（dev環境）

poetry add <packeage_name> -G <group_name>

<group_name>グループとしてパッケージがインストールされます。

<group_name>は任意の名前を設定できますが、一般的に「dev」を使用します。

グループは複数作成できますが、パッケージをインストールできるのはメインを含むどれか１つのグループだけです。

アンインストール（dev環境）

poetry remove <packeage_name>

オプション-G <group_name>でグループ名も指定できますが、パッケージは１グループにしかインストールできないので、付けなくても問題ないです。

全てのパッケージをインストール（dev環境を除く）

デプロイ時など、メインにインストールしたパッケージのみインストールし、グループのパッケージはインストールしない時は、グループを除外してインストールします。

poetry install --without <group_name>

仮想環境

仮想環境は自動で作られ、自動で出入りしてくれるのであまり意識することはないのですが、クリーンアップしたい時があるので、場所の確認と削除方法は知っておいた方がいいです。

仮想環境の場所

% poetry env info

Virtualenv
Python:         3.12.10
Implementation: CPython
Path:           /home/local/.cache/pypoetry/virtualenvs/poetry-demo4-va9Qhg8P-py3.12
Executable:     /home/local/.cache/pypoetry/virtualenvs/poetry-demo4-va9Qhg8P-py3.12/bin/python
Valid:          True