【Poetry使い方から仮想環境の削除まで】Pythonパッケージ管理の完全ガイド

最近では、pip の代わりに Poetry を導入する Python プロジェクトも増えてきました。

たしかに pip は役割がシンプルで使い方も単純明快ですが、仮想環境の構築には他のツールが必要だったり、依存関係の解決は開発者自身で行う必要がありました。

一方の Poetry 、誤解を恐れずに表現するなら以下のような感じです。

pip + virtualenv + requirements.txt

上記に加えてさらに「依存関係の自動調整」までやってくれます。

使い始めると離れられないほど便利な一方で、多機能ゆえのとっつきにくさがあることも事実でしょう。

そこで、本記事は以下の内容をお伝えします。

最初こそ pip との違いに戸惑いますが、いざ使ってみると pip には戻れないほどに便利なツールです。

本記事で Poetry の基本的な使い方をマスターしていきましょう！

「パッケージ = ライブラリ + フレームワーク」とイメージいただくと分かりやすいと思います。

Poetry ってどんなもの？

まずは基本から。

Poetry はどんなものなのか？を解説します。

そもそも、Poetry って何？

Poetry は以下の機能を提供します。

一方で、pip は「パッケージのインストール」に特化したツールです。

通常は pip 単体で使うことはまれで、仮想環境を構築するためには別コマンドを使ったり、依存関係の管理を行うために requirements.txt を併用する必要があります。

ここからは Poetry のメリットを少し掘り下げて解説します。

パッケージの管理

pip と同様にパッケージ管理が行えます。

これだけ見ると 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つのファイルを扱うことになります。

この二つを合わせて、requirements.txt の働きをすると考えると分かりやすいでしょう。

簡単に両方のファイルの役割を解説します。

pyproject.toml

poetry addコマンドでパッケージを追加すると、pyproject.toml ファイルが更新されます。

このファイルでは、プロジェクトの依存パッケージとそのバージョンの「範囲」を定義します。

pyproject.toml はパッケージを「インストール」するわけではなく、あくまで依存関係を「宣言」するだけです。

poetry.lock

パッケージの依存関係を解決し、具体的なバージョンを固定するために、poetry.lock ファイルが使用されます。

pyproject.toml に基づいて依存関係の解決が行われた後（例えば poetry install コマンド実行時に）、Poetry はこの解決結果を poetry.lock に記録します。

これにより、インストールされるパッケージのバージョンが確定されます。

Poetry のインストール方法

Poetry がどんなものか理解できたところで、実際の使い方の解説に入っていきます。

インストールは２段階です。

ここでは Mac の場合で解説します。

Windows など、他のOSをお使いの方は公式 HP でご確認ください。
» Poetry | Documentation

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

設定ファイルの中に以下の３行をコピペします。

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オプションをつけたパッケージはインストールされません。

pyproject.toml の [dev-dependencies] セクションに記述されます。

プロジェクトをクローンした場合のライブラリインストール

プロジェクトをクローンした直後にはパッケージが何も入っていないので、以下のコマンドでパッケージを一括インストールします。

poetry install

本番環境で、開発時のみに利用するパッケージをインストール対象から除外したい場合は、以下のコマンドを実行します。

poetry install --no-dev

開発時のみに使うパッケージを指定してインストールする方法は、こちらの項目を参考にしてください。

pip install -r requirements.txtと同じような挙動になります。

パッケージの削除

パッケージの削除は、以下のコマンドを実行します。

poetry remove パッケージ名

パッケージのアップデート

パッケージをアップデートするには、以下のコマンドを実行します。

poetry update

Poetry の使い方：仮想環境編

仮想環境ファイルの配置場所をプロジェクトのルートにする

Poetry のデフォルト設定では、変な場所に仮想環境が作られてしまいます。

仮想環境をプロジェクトのルートディレクトリに変更したい場合には、以下のコマンドを実行します。

poetry config virtualenvs.in-project true

このコマンドにより、プロジェクトのルートディレクトリに.venvファイルが作成されるようになります。

デフォルトの設定よりも管理しやすくなるはずです。

poetry config --list

使用する Python バージョンの選択

仮想環境の Python バージョンを指定するため、以下のコマンドを実行します。

poetry env use 3.11

これでプロジェクトのルートに.venvディレクトリが生成されます。

事前に、対象のバージョンの Python をインストールしてください。pyenv を使う場合は、こちらを参考にしていただけます。

仮想環境の削除

誤って仮想環境を作成してしまったら、まず最初に現状を確認します。

Poetry の仮想環境をリストで出力しましょう。

poetry env list

削除したい仮想環境名を確認したら、以下のコマンドを実行します。

poetry env remove 仮想環境名

最後にpoetry env listコマンドで仮想環境が消えていることを確認してください。

僕はプロジェクトのルートに.venvを保存する設定を忘れてしまった時に、この仮想環境の削除をして再セットアップしました。

仮想環境に入る

仮想環境に入るには、次のコマンドを使います。

poetry shell

source venv/bin/activate と似たようなものだと考えれば OK です。

仮想環境から抜ける

仮想環境から抜けるには、以下のコマンドを実行します。

deactivate

これにより Poetry の仮想環境が非アクティブになり、システムのグローバルな Python 環境に戻ります。

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

これからプロジェクトを立ち上げる場合はnewまたはinitを実行します。

もしPythonプロジェクトのディレクトリがまだないなら、newコマンドでディレクトリごと作成します。

poetry new <プロジェクトの名前>

一方ですでにあるプロジェクトをPoetry管理下に置く場合は、以下のコマンドを実行します。

poetry init

new と違って、init では次のようなことを聞かれます。一つずつ答えていきましょう。

質問に答えた内容が 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.2.3-alpha といった書き方でも大丈夫です。

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"

例えば次のようなライセンスを設定します。

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"

参考サイト