- Poetry ってどんなもの?
- インストール方法が知りたい
- 使い方を詳しく教えて欲しい
最近では、pip の代わりに Poetry を導入する Python プロジェクトも増えてきました。
たしかに pip は役割がシンプルで使い方も単純明快ですが、仮想環境の構築には他のツールが必要だったり、依存関係の解決は開発者自身で行う必要がありました。
一方の Poetry 、誤解を恐れずに表現するなら以下のような感じです。
pip + virtualenv + requirements.txt
上記に加えてさらに「依存関係の自動調整」までやってくれます。
使い始めると離れられないほど便利な一方で、多機能ゆえのとっつきにくさがあることも事実でしょう。
そこで、本記事は以下の内容をお伝えします。
- Poetry ってどんなもの?
- インストール方法と使い方
- pyproject.toml ファイルの書き方
最初こそ pip との違いに戸惑いますが、いざ使ってみると pip には戻れないほどに便利なツールです。
本記事で Poetry の基本的な使い方をマスターしていきましょう!
Poetry ってどんなもの?
まずは基本から。
Poetry はどんなものなのか?を解説します。
そもそも、Poetry って何?
Poetry は以下の機能を提供します。
- パッケージの管理
- 仮想環境の管理
- 依存関係・互換性の調整(強化版)
一方で、pip は「パッケージのインストール」に特化したツールです。
通常は pip 単体で使うことはまれで、仮想環境を構築するためには別コマンドを使ったり、依存関係の管理を行うために requirements.txt を併用する必要があります。
ここからは Poetry のメリットを少し掘り下げて解説します。
パッケージの管理
pip と同様にパッケージ管理が行えます。
処理内容 | pip | Poetry |
---|---|---|
追加 | pip install | poetry add |
削除 | pip uninstall | poetry remove |
更新 | pip install –upgrade | poetry update |
これだけ見ると pip との差はないようにも思えます。
ところが、次から説明する「仮想環境の管理」と「依存関係・互換性の調整」という機能を知ると、Poetry を使うメリットが分かっていただけると思います。
仮想環境の管理
Poetry を使うと、そのプロジェクト固有の仮想環境が自動的に構築されます。
標準ライブラリでもpython -m venv
というコマンドで仮想環境を構築できるものの、Poetry には仮想環境構築がデフォルトで搭載されているのが強みです。
つまり Poetry を採用するだけで、仮想環境を構築することをチームのスタンダードにできます。
これにより異なるプロジェクト間でライブラリのバージョンの衝突をさけ、環境を隔離して安全に作業できるようになります。
依存関係・互換性の調整(強化版)
一般的なプロジェクトでは、複数のパッケージを利用することがほとんどだと思います。
そこで問題になるのが、依存関係・互換性の問題です。
異なるパッケージが、ある特定のパッケージの別バージョンを求めることがあります。
例えば pandas と scikit-learn はともに NumPy が必要です。
pandas が NumPy の 1.19 以降を要求している一方で、scikit-learn は NumPy の 1.18 以降を要求しているとします。
この時には NumPy の 1.19 以降をインストールしないといけません。
このように利用するバージョンの交通整理が必要になることがあり、これを依存関係・互換性の調整といいます。
pip の場合は開発者が requirements.txt の中身を目視で確認して、各パッケージのインストールすべきバージョンを決めていくという作業が必要でした。
これでは扱うパッケージが増えると大変。
Poetry を導入するだけで、これまで人間が目視で行っていた依存関係の調整も自動化できるというわけです。
Poetry で登場するファイルの種類
Poetry では、以下の2つのファイルを扱うことになります。
- pyproject.toml
- poetry.lock
この二つを合わせて、requirements.txt の働きをすると考えると分かりやすいでしょう。
簡単に両方のファイルの役割を解説します。
pyproject.toml
poetry add
コマンドでパッケージを追加すると、pyproject.toml ファイルが更新されます。
このファイルでは、プロジェクトの依存パッケージとそのバージョンの「範囲」を定義します。
pyproject.toml はパッケージを「インストール」するわけではなく、あくまで依存関係を「宣言」するだけです。
poetry.lock
パッケージの依存関係を解決し、具体的なバージョンを固定するために、poetry.lock ファイルが使用されます。
pyproject.toml に基づいて依存関係の解決が行われた後(例えば poetry install コマンド実行時に)、Poetry はこの解決結果を poetry.lock に記録します。
これにより、インストールされるパッケージのバージョンが確定されます。
Poetry のインストール方法
Poetry がどんなものか理解できたところで、実際の使い方の解説に入っていきます。
インストールは2段階です。
- pyenv のインストール
- Poetry のインストール
ここでは Mac の場合で解説します。
pyenv のインストール
複数バージョンの Python をインストールすることを想定して、pyenv を導入します。
まずは HomeBrew をインストール。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
最後に以下のようなコメントが表示されます。
==> Next steps:
- Run these two commands in your terminal to add Homebrew to your PATH:
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/username/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
- Run brew help to get started
- Further documentation:
https://docs.brew.sh
上でハイライトした行で示されているコマンドを実行するよう、指示があります。
指示に従ってコマンドを実行してください。
続いて、先ほどインストールした HomeBrew を使って pyenv をインストールしましょう。
brew install pyenv
pyenv のインストールが終わったら、pyenv のパスを通します。
以下のいずれかのコマンドで、シェルの設定ファイルを開いてください。
# Zsh の場合
vi ~/.zshrc
# Bash の場合
vi ~/.bashrc
設定ファイルの中に以下の3行をコピペします。
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv virtualenv-init -)"
最後に Esc を押してから、以下の Vim コマンドを実行して上書き保存しましょう。
:wq
これで pyenv を使うための準備が整いました。
早速 pyenv でインストールできる Python のバージョンを確認してみます。
pyenv install --list
インストールしたい Python のバージョンが決まったら、pyenv を使ってインストールしていきましょう。ここでは3.11.7
をインストールしてみます。
pyenv install 3.11.7
さらに以下のコマンドで、システム全体でグローバルに使えるようにします。
pyenv global 3.11.7
最後に Python がインストールされたかを以下のコマンドで確認します。
python --version
Python 3.11.7
という文字列が返ってくれば、インストールは完了です。
Poetry のインストール
以下のインストールコマンドを実行します。
# Linux, macOS, Windows (WSL)
curl -sSL https://install.python-poetry.org | python3 -
上記を実行すると、以下のようなメッセージが表示されます。
Retrieving Poetry metadata
# Welcome to Poetry!
This will download and install the latest version of Poetry,
a dependency and package manager for Python.
It will add the `poetry` command to Poetry's bin directory, located at:
/Users/username/.local/bin
You can uninstall at any time by executing this script with the --uninstall option,
and these changes will be reverted.
Installing Poetry (1.7.1): Done
Poetry (1.7.1) is installed now. Great!
To get started you need Poetry's bin directory (/Users/username/.local/bin) in your `PATH`
environment variable.
Add `export PATH="/Users/username/.local/bin:$PATH"` to your shell configuration file.
Alternatively, you can call Poetry explicitly with `/Users/username/.local/bin/poetry`.
You can test that everything is set up by executing:
`poetry --version`
長々と書いてありますが、要はハイライトした行に書いてあるスクリプトをシェルの設定ファイルに追記するだけです。
まずはお使いのシェルに応じて、以下のいずれかのコマンドを実行してシェルの設定ファイルを開きます。
# Zsh の場合
vi ~/.zshrc
# Bash の場合
vi ~/.bashrc
先ほどのメッセージで表示されていたコマンドを追記します。
export PATH="/Users/username/.local/bin:$PATH"
コマンドが入力できたら、Esc キーを押してから以下の Vim コマンドを実行します。
:wq
最後に source コマンドで設定を恒久化します。
# zsh の場合
source ~/.zshrc
# bash の場合
source ~/.bashrc
Poetry の使い方:パッケージ管理編
プロジェクトのルートディレクトリに.venvファイルを置く場合には、あらかじめ以下のコマンドを実行しておきましょう。
poetry config virtualenvs.in-project true
これを踏まえて、パッケージ管理に必要なコマンドを解説します。
ライブラリのインストール
ライブラリのインストールは、以下のコマンドを実行します。
poetry add パッケージ名
上記を実行すると、pyproject.toml にインストールしたライブラリ名とバージョンが追記されます。
pip だとpip freeze
が必要でした。
Poetry ならパッケージ追加時に pyproject.toml への追記を自動で行なってくれるので、管理がとても楽です。
開発中だけ使うライブラリのインストール
本番環境では使わないパッケージは、--dev
オプションをつけると便利です。
poetry add パッケージ名 --dev
こうしておくと、pyproject.toml に開発中のみ使うパッケージとして記録されます。
本番環境のインストール時には、以下のコマンドを実行します。
poetry install --no-dev
これで--dev
オプションをつけたパッケージはインストールされません。
プロジェクトをクローンした場合のライブラリインストール
プロジェクトをクローンした直後にはパッケージが何も入っていないので、以下のコマンドでパッケージを一括インストールします。
poetry install
本番環境で、開発時のみに利用するパッケージをインストール対象から除外したい場合は、以下のコマンドを実行します。
poetry install --no-dev
開発時のみに使うパッケージを指定してインストールする方法は、こちらの項目を参考にしてください。
パッケージの削除
パッケージの削除は、以下のコマンドを実行します。
poetry remove パッケージ名
パッケージのアップデート
パッケージをアップデートするには、以下のコマンドを実行します。
poetry update
Poetry の使い方:仮想環境編
仮想環境ファイルの配置場所をプロジェクトのルートにする
Poetry のデフォルト設定では、変な場所に仮想環境が作られてしまいます。
仮想環境をプロジェクトのルートディレクトリに変更したい場合には、以下のコマンドを実行します。
poetry config virtualenvs.in-project true
このコマンドにより、プロジェクトのルートディレクトリに.venv
ファイルが作成されるようになります。
デフォルトの設定よりも管理しやすくなるはずです。
次のコマンドで設定が確認できます。
poetry config --list
使用する Python バージョンの選択
仮想環境の Python バージョンを指定するため、以下のコマンドを実行します。
poetry env use 3.11
これでプロジェクトのルートに.venv
ディレクトリが生成されます。
仮想環境の削除
誤って仮想環境を作成してしまったら、まず最初に現状を確認します。
Poetry の仮想環境をリストで出力しましょう。
poetry env list
削除したい仮想環境名を確認したら、以下のコマンドを実行します。
poetry env remove 仮想環境名
最後にpoetry env list
コマンドで仮想環境が消えていることを確認してください。
仮想環境に入る
仮想環境に入るには、次のコマンドを使います。
poetry shell
source venv/bin/activate
と似たようなものだと考えれば OK です。
仮想環境から抜ける
仮想環境から抜けるには、以下のコマンドを実行します。
deactivate
これにより Poetry の仮想環境が非アクティブになり、システムのグローバルな Python 環境に戻ります。
プロジェクトのセットアップ
これからプロジェクトを立ち上げる場合はnew
またはinit
を実行します。
もしPythonプロジェクトのディレクトリがまだないなら、newコマンドでディレクトリごと作成します。
poetry new <プロジェクトの名前>
一方ですでにあるプロジェクトをPoetry管理下に置く場合は、以下のコマンドを実行します。
poetry init
new と違って、init では次のようなことを聞かれます。一つずつ答えていきましょう。
- Package name: パッケージの名前
- Version: バージョン
- Description: 説明文
- Author: 作成者
- License: ライセンス
- Compatible Python versions: Pythonのバージョン
質問に答えた内容が pyproject.toml に反映されます。
pyproject.toml ファイルの書き方
Poetry では pyproject.toml の[tool.poetry]
というセクションにプロジェクトの詳細を書き込むようになっています。
これは poetry init コマンドを実行した時に反映される項目であり、初見ではどういった意味かわからない箇所もあるはず。
本セクションでは、[tool.poetry]
セクションに書く内容を解説します。
name
プロジェクトをあらわすような、わかりやすい名前をつけます。
[tool.poetry]
name = "my_blog"
仮に PyPI などのパッケージリポジトリに公開する時はこの name が識別子になるので、他のパッケージと重複しないように名前をつける必要があります。
とはいえ、個人開発で PyPI などに公開しないのであればわかりやすい名前をつけるで大丈夫です。
version
プロジェクトのバージョンを記載します。
プロジェクトの更新のたびにバージョンを上げていく必要があり、一般的にはセマンティックバージョニングと呼ばれる管理を行います。
[tool.poetry]
version = "1.2.3"
それぞれの桁ごとの意味合いは以下の通りです。
- 1桁目:MAJOR 。互換性のないAPIの変更がある場合に上げる。
- 2桁目:MINOR 。互換性のある新機能が追加された場合に上げる。
- 3桁目:PATCH 。互換性のあるバグ修正が行われた場合に上げる。
description
プロジェクトの説明を簡潔に書きます。
[tool.poetry]
description = "A robust and user-friendly blog system designed for both individual bloggers and enterprise-level content management."
書き方のポイントは以下の通りです。
- 簡潔:ポイントを絞って短く書く
- 明瞭:何をするプログラムなのか
- 対象者:どのような用途でどんな人が使うのか
license
ライセンスを記述します。
[tool.poetry]
license = "MIT"
例えば次のようなライセンスを設定します。
- Apache-2.0
- BSD-2-Clause
- BSD-3-Clause
- BSD-4-Clause
- GPL-2.0-only
- GPL-2.0-or-later
- GPL-3.0-only
- GPL-3.0-or-later
- LGPL-2.1-only
- LGPL-2.1-or-later
- LGPL-3.0-only
- LGPL-3.0-or-later
- MIT
author
プロジェクトの作成者を記述します。
[tool.poetry]
authors = [
"Steive <sample@gmail.com>",
]
形式は name<email> の形式で指定してください。
maintainers
保守を行う人がいれば、記述します。
[tool.poetry]
maintainers = [
"Emilly<sample@gmail.com>",
"Bob<sample@gmail.com>",
]
プロジェクトのオーナー以外にメンテナンスを行う人を分けて書いて置けるのは便利です。
readme
README ファイルへのパスを記載する場所です。
[tool.poetry]
readme = "README.md"
一般的に README ファイルには以下のような事項が書かれます。
- プロジェクトの概要と目的
- インストール手順
- 使用方法やサンプルコード
- コントリビューションガイドライン
- ライセンス情報
- 連絡先や貢献者の情報
homepage [ オプション ]
プロジェクトに関するホームページがあれば記載しましょう。
[tool.poetry]
homepage = "https://www.sample.com"
repository [ オプション ]
プロジェクトのリポジトリ URL を記載します。
[tool.poetry]
repository = "https://github.com/~~~"
documentation [ オプション ]
ドキュメントの URL があれば記載します。
[tool.poetry]
documentation = "https://sample.com/docs"
コメント