【Python】Poetryの使い方をまとめてみた【パッケージ管理】

  • Poetryとは?
  • Poetryの基本的な使い方や応用とは?

本記事ではこのような疑問を解決します。

Pythonのパッケージ管理ツールとして最も一般的なのはpipと言えるでしょう。

筆者もPythonで開発を行うようになってからしばらくはpipを使っていました。

しかし、あるプロジェクトに参画した際に、
表題にあるPoetryというパッケージ管理ツールを扱ってからは、
その便利さゆえにPoetryしか使わなくなったのです。


そこで今回はPoetryの基本的な使い方から応用までを解説します。

Poetryとは?

PoetryとはPythonのパッケージ管理ツールのことです。

Pythonにはpipやpipenvなどのパッケージ管理ツールがいくつかありますが、
Poetryもそのうちの1つになります。

そして、Poetryの機能は以下の通りです。

・パッケージの管理

・依存関係の解決(poetry.lock)

・プロジェクト管理ファイルの生成(pyproject.toml)

・仮想環境の自動作成

・パッケージのビルドと公開

なお、上記Poetry機能の中で多く使うのは上から4つの機能(パッケージの管理~仮想環境の自動作成)であると言えるでしょう。

※本記事ではパッケージのビルドと公開の操作方法については省略

Poetryのインストール

まずはPoetryをインストールしていきましょう。

また、Poetryを使うためにはPythonがインストールされている必要があります。

具体的にはPython 2.7あるいはPython 3.5以降のバージョンです。

Poetryインストールのコマンドについては以下をご参照ください。

osx / linux / bashonwindows用インストールコマンド

windows powershell用インストールコマンド

インストールを行うと、
Unixでは$HOME/に、Windowsでは%USERPROFILE%\に.poetryディレクトリが生成されます。

Poetryの使い方(基本的な流れ)

ここでは初めてPoetryを使う時の基本的な流れを解説していきます。

プロジェクトのセットアップ

最初に以下のコマンドを実行してプロジェクトを作成します。

$ poetry new 【任意のプロジェクト名】

作成されたディレクトリの中にpyproject.tomlというプロジェクト管理ファイルが生成されます。

pyproject.tomlには作成したプロジェクトに関するメタデータや依存関係が記述されます。


なお、既存プロジェクトがある場合は、
既存プロジェクト内で以下のコマンドを実行してPoetry管理を行うことができます。

$ poetry init

上記コマンド実行によりディレクトリ内にpyproject.tomlが生成されます。

パッケージの追加など

次にパッケージの追加等を行います。

以下のコマンドを実行してパッケージを追加しましょう。

$ poetry add 【パッケージ名】

パッケージが追加(インストール)されると、poetry.lockというファイルが生成されます。

poetry.lockは仮想環境にインストールされているパッケージや依存パッケージ、そのバージョンが一覧で記述されているファイルです。

なお、このpoetry.lockについては後ほど詳しく説明します。


一方、パッケージを削除する場合は以下の通り。

$ poetry remove 【パッケージ名】

なお、追加されているパッケージを確認したい場合は、
以下のコマンドで追加パッケージ一覧を表示できます。

$ poetry show

仮想環境の使用

パッケージの追加を行うと仮想環境が生成されます。

仮想環境を使用する場合はプロジェクト内*(どこでもOK)で以下のコマンドを実行します。
*pyproject.tomlがあるディレクトリorそれ以下のディレクトリ

$ poetry shell

これで仮想環境に入れたので、インストールしたパッケージが使用可能になります。


なお、仮想環境を出たい時は以下のコマンドです。

$ exit

ここまで仮想環境に入る方法を解説してきましたが、
いちいち仮想環境に入ったり出たりするのは面倒くさく感じます。

そこで以下のコマンドを実行することにより仮想環境の外から操作することができます。
(というより、基本的に以下のコマンドしか使わなくなる)

$ poetry run 【仮想環境内でのコマンド】

さらに、この仮想環境がどこに置かれているのか?
Pythonはどのバージョンを利用しているのか?という疑問が出てきます。

それらを確認できるのが以下のコマンドです。

$ poetry env info

Virtualenv
Python: 3.10.5
Implementation: CPython
Path: /Users/kosuke/Library/Caches/pypoetry/virtualenvs/sample-6dcV04nZ-py3.10
Valid: True

System
Platform: darwin
OS: posix
Python: /Users/kosuke/.pyenv/versions/3.10.5

上記のVirtualenv内Pathの値が仮想環境が置いてある場所になります。

また、System内Pythonの値が利用されているPythonのバージョンになります。

もしこちらの仮想環境が不要になった場合、どんどん溜まっていくので削除しても良いでしょう。

Poetryの使い方(その他)

ここでは知っておくと便利な使い方をご紹介します。

既存プロジェクトにおけるパッケージのインストール

既存プロジェクトにおいてpyproject.tomlにパッケージの依存関係が定義されている場合は、
以下のコマンドでパッケージの一括インストールができます。

$ poetry install

なお、こちらのコマンドはpoetry.lockが存在しているかいないかで実行結果に以下のような違いが生じます。

・poetry.lockが存在していない場合

pyproject.tomlに記載されたすべてのパッケージの依存関係を解決し、インストールが行われます。
また、インストールされる依存パッケージは最新バージョンのものです。
この場合、インストールされたパッケージと依存パッケージ、その正確なバージョンが記載されたpoetry.lockが生成されます。

・poetry.lockが存在している場合

pyproject.tomlに記載されたすべてのパッケージの依存関係が解決されるとともに、poetry.lockに記載されたパッケージの正確なバージョンに従ってインストールが行われます。
つまり、誰がどんな環境でインストールを行なっても同じパッケージたちをインストールすることができます。
一方、新たに他のパッケージを追加する場合は依存関係の解決ができずエラーを吐くこともあるでしょう。
ただ、チーム開発を行う場合はどのメンバーでも同じパッケージリストの状態を維持する必要があるため、poetry.lockをGitHub等にアップすることが推奨されています。

仮想環境で利用するPythonバージョンの指定・変更

まずは利用したいPythonバージョンをpyenv等でインストールしておきます。

次にpyproject.toml内のPythonバージョンの記述を利用したいバージョンに変更します。

[tool.poetry.dependencies]
python = "^3.9.1"

そして、以下のコマンドを実行すると変更が反映されます。

$ poetry env use 【利用したいPython実行ファイルへのパス】
例)poetry env use /Users/kosuke/.pyenv/versions/3.9.1/bin/python3

なお、こちらのコマンドで変更されたことが確認するといいでしょう。

$ poetry env info

まとめ

以上がPoetryの使い方になります。

今回ご紹介した使い方を押さえれば、
Poetryを使った開発においては一連の工程を行うことができるかと思います。

なお、Poetryには他にも様々な機能があるため、公式ドキュメントを読んでみると面白いでしょう。