Pythonでの開発において、ライブラリの依存関係管理や仮想環境の構築は、プロジェクトの安定性を左右する極めて重要な要素です。

長らく pip と requirements.txt による管理が主流でしたが、複雑な依存関係の解決やバージョン競合の防止には限界がありました。

そこで登場したのが Poetry です。

Poetryは、パッケージのインストール、依存関係の解決、ビルド、そして公開までを一つのツールで完結させるモダンなパッケージマネージャーです。

本記事では、Poetryの基本概念からインストール方法、実務で役立つ具体的なコマンドまで、詳細に解説していきます。

目次 [ close ]
  1. Poetryとは
  2. Poetryを導入するメリット
    1. 依存関係の高度な解決能力
    2. 仮想環境の自動管理
    3. 開発用ライブラリの分離
  3. Poetryのインストール方法
    1. 公式インストーラーを使用したインストール
    2. インストールの確認とパスの設定
  4. Poetryの初期設定とプロジェクト作成
    1. 新規プロジェクトの作成 (poetry new)
    2. 既存ディレクトリでの初期化 (poetry init)
    3. 仮想環境の作成場所を変更する
  5. パッケージの管理方法
    1. ライブラリの追加 (poetry add)
    2. 開発用ライブラリの追加
    3. ライブラリの削除 (poetry remove)
    4. ライブラリの一覧表示 (poetry show)
  6. 依存関係の解決と poetry.lock の重要性
  7. 仮想環境の運用とコマンド実行
    1. poetry run コマンド
    2. poetry shell コマンド
  8. 実践的な pyproject.toml の構成
  9. 既存の requirements.txt からの移行
  10. Poetry を使ったパッケージのビルドと公開
    1. ビルドの実行
    2. PyPI への公開
  11. よく使う Poetry コマンドリファレンス
  12. Poetry を Docker で活用する際のコツ
  13. トラブルシューティング：困ったときは
    1. 依存関係の解決がいつまでも終わらない
    2. Python バージョンの不一致
  14. まとめ

Poetryとは

Poetryは、Pythonプロジェクトのパッケージ管理とビルドシステムを統合したツールです。

従来の pip、setuptools、venv、twine といった複数のツールに分かれていた機能を、Poetryという単一のコマンドラインツールで提供します。

最大の特長は、pyproject.toml というファイルを使用してプロジェクトの設定を一元管理する点にあります。

これは Python の標準仕様である PEP 518 および PEP 517 に準拠しており、プロジェクトのメタデータ、依存ライブラリ、開発ツール（LinterやFormatterなど）の設定を一つのファイルにまとめることができます。

また、Poetryは 「決定論的な依存関係の解決」 を得意としています。

あるライブラリが依存している別のライブラリのバージョンまで厳密に計算し、poetry.lock ファイルに記録します。

これにより、チーム開発において「自分の環境では動くが、他の人の環境では動かない」といった、バージョン齟齬に起因するトラブルを劇的に減らすことが可能です。

Poetryを導入するメリット

Poetryを導入することで、Python開発のワークフローは劇的に改善されます。

ここでは、主な3つのメリットを深掘りします。

依存関係の高度な解決能力

従来の pip では、ライブラリ A とライブラリ B がそれぞれ異なるバージョンのライブラリ C を要求している場合、インストール順序によっては環境が壊れてしまうことがありました。

Poetryはインストール前にすべての依存関係をスキャンし、矛盾のない最適なバージョンの組み合わせを自動的に算出します。

仮想環境の自動管理

Poetryは、プロジェクトごとに独立した仮想環境を自動的に作成・管理します。

ユーザーは自分で python -m venv .venv といったコマンドを打つ必要がなく、パッケージを追加した瞬間に適切な環境が用意されます。

また、仮想環境の場所をプロジェクトディレクトリ直下に設定することも可能で、VS Code などの IDE との相性も抜群です。

開発用ライブラリの分離

テストツールの pytest や、コード整形ツールの black など、本番環境には不要だが開発時には必要なライブラリを「依存関係グループ」として明確に分けることができます。

これにより、本番環境（本番用イメージ）の軽量化とセキュリティの向上が図れます。

Poetryのインストール方法

Poetryを使い始めるには、まずシステムに Poetry 本体をインストールする必要があります。

OSごとの推奨される方法を解説します。

公式インストーラーを使用したインストール

公式が推奨しているのは、専用のインストールスクリプトを使用する方法です。

これにより、システムの Python 環境を汚さずに Poetry を隔離された状態でインストールできます。

Windows (PowerShell) の場合

PowerShellを開き、以下のコマンドを実行します。

PowerShell
# インストールスクリプトの実行
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

macOS / Linux の場合

ターミナルで以下のコマンドを実行します。

Shell
# curlを使用してインストールスクリプトを実行
curl -sSL https://install.python-poetry.org | python3 -

インストールの確認とパスの設定

インストールが完了したら、以下のコマンドでバージョンが表示されるか確認します。

Shell
# バージョン確認
poetry --version

もし「コマンドが見つかりません」と表示される場合は、Poetry のバイナリが配置されたディレクトリを環境変数 PATH に追加する必要があります。

通常、macOS/Linux では $HOME/.local/bin、Windows では %APPDATA%\Python\Scripts にインストールされます。

Poetryの初期設定とプロジェクト作成

Poetryをインストールしたら、プロジェクトの作成方法を学びましょう。

新規にプロジェクトを作る場合と、既存のプロジェクトに導入する場合の2パターンがあります。

新規プロジェクトの作成 (poetry new)

新しくプロジェクトを開始する場合は、poetry new コマンドを使用します。

Shell
# プロジェクトの作成
poetry new my-python-project

このコマンドを実行すると、以下のようなディレクトリ構造が自動生成されます。

my-python-project/
├── pyproject.toml
├── README.md
├── my_python_project/
│   └── __init__.py
└── tests/
    └── __init__.py

既存ディレクトリでの初期化 (poetry init)

すでに存在するソースコードに対して Poetry を導入する場合は、そのディレクトリに移動して poetry init を実行します。

Shell
# 既存ディレクトリへ移動
cd existing-project
# インタラクティブな設定開始
poetry init

実行すると、プロジェクト名やバージョン、依存ライブラリなどを対話形式で質問されます。

すべて入力し終えると、pyproject.toml が生成されます。

仮想環境の作成場所を変更する

デフォルトでは、Poetry は仮想環境をユーザーホームディレクトリ配下の特定の場所に作成します。

しかし、開発の利便性を考えると、プロジェクトディレクトリ内に .venv フォルダを作成する設定に変更しておくのが一般的です。

Shell
# 仮想環境をプロジェクト内に作成するように設定
poetry config virtualenvs.in-project true

この設定を行っておくことで、「プロジェクト内の .venv」 が優先的に使用されるようになり、エディタの設定などが非常にスムーズになります。

パッケージの管理方法

Poetry を使用したライブラリの追加、削除、更新方法を解説します。

ライブラリの追加 (poetry add)

プロジェクトに新しいライブラリを追加するには、poetry add を使用します。

Shell
# requestsライブラリを追加
poetry add requests
実行結果
Using version ^2.31.0 for requests

Updating dependencies
Resolving dependencies... (0.3s)

Package operations: 5 installs, 0 updates, 0 removals

  Installing certifi (2023.7.22)
  Installing charset-normalizer (3.3.2)
  Installing idna (3.4)
  Installing urllib3 (2.0.7)
  Installing requests (2.31.0)

Writing lock file

このコマンドを実行すると、pyproject.toml にライブラリが追記され、さらに詳細な依存関係が poetry.lock に記録されます。

開発用ライブラリの追加

テストツールや Lint ツールなど、開発時のみ必要なパッケージは --group dev オプションを付けて追加します。

Shell
# 開発用グループにpytestを追加
poetry add pytest --group dev

ライブラリの削除 (poetry remove)

不要になったライブラリを削除する場合は、remove コマンドを使用します。

Shell
# requestsを削除
poetry remove requests

ライブラリの一覧表示 (poetry show)

現在インストールされているパッケージを確認するには show を使います。

Shell
# インストール済みパッケージのツリー表示
poetry show --tree

依存関係の解決と poetry.lock の重要性

Poetry を語る上で欠かせないのが、poetry.lock ファイルの役割です。

pyproject.toml には、例えば requests = "^2.31.0" のように、許容されるバージョンの範囲が記述されます。

これに対し、poetry.lock には 実際にインストールされた特定のバージョン（例: 2.31.0）とそのハッシュ値 が詳細に記録されます。

チーム開発においては、この poetry.lock を必ず Git などのバージョン管理に含める必要があります。

他の開発者がリポジトリをクローンし、poetry install を実行すると、Poetry は pyproject.toml を無視して poetry.lock に書かれた通りのバージョンを正確に再現します。

これにより、「環境によって動作が異なる」という問題を根絶できるのです。

仮想環境の運用とコマンド実行

Poetry で作成した仮想環境内で Python スクリプトを実行する方法は主に2つあります。

poetry run コマンド

仮想環境をアクティブにすることなく、その環境の Python やコマンドを直接実行する方法です。

Shell
# 仮想環境内のPythonでスクリプトを実行
poetry run python main.py

# 仮想環境内のpytestを実行
poetry run pytest

poetry shell コマンド

現在のターミナルセッションを仮想環境内に入り込ませる（アクティベートする）方法です。

Shell
# 仮想環境を起動
poetry shell

# (仮想環境内)
python main.py
# 終了するには exit
exit

基本的には、単発の実行であれば poetry run を、連続して作業を行う場合は poetry shell を使うのが効率的です。

実践的な pyproject.toml の構成

Poetry の設定ファイルである pyproject.toml の具体的な内容を見てみましょう。

このファイルは、プロジェクトの「設計図」となります。

TOML
[tool.poetry]
name = "my-sample-app"
version = "0.1.0"
description = "Poetryを使用したサンプルプロジェクト"
authors = ["Taro Yamada <taro@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.31.0"
pandas = ">=2.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^23.9.1"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

各セクションの役割は以下の通りです。

セクション名説明
[tool.poetry]プロジェクト名、バージョン、著者などの基本情報。
[tool.poetry.dependencies]本番環境でも必要なメインの依存ライブラリ。
[tool.poetry.group.dev.dependencies]テストやデバッグなどの開発時にのみ使用するライブラリ。
[build-system]Poetry 自体がビルドに使用するバックエンドの設定（通常は変更不要）。

既存の requirements.txt からの移行

すでに requirements.txt で管理されているプロジェクトを Poetry に移行するのも簡単です。

まずプロジェクトディレクトリで poetry init を行い、pyproject.toml を作成します。

その後、以下のコマンドを組み合わせて一括で追加できます。

Shell
# macOS/Linuxの場合: requirements.txtから一括追加
cat requirements.txt | xargs poetry add

Windows の場合は、PowerShell で以下のように実行します。

PowerShell
# Windowsの場合: requirements.txtから一括追加
Get-Content requirements.txt | ForEach-Object { poetry add $_ }

Poetry は追加時に依存関係を自動解決するため、もし requirements.txt 内に競合する設定があれば、この時点で警告が表示されます。

これは環境の健全性を確認する良い機会になります。

Poetry を使ったパッケージのビルドと公開

Poetry はライブラリ開発者にとっても強力なツールです。

自分の作成したパッケージを PyPI (Python Package Index) に公開する手順も簡略化されています。

ビルドの実行

ソースコードを配布可能な形式（sdist や wheel）にパッケージングします。

Shell
# ビルドの実行
poetry build

実行後、dist/ ディレクトリに .tar.gz ファイルと .whl ファイルが生成されます。

PyPI への公開

作成したパッケージを公開するには、publish コマンドを使います。

Shell
# 公開（事前にAPIトークンの設定が必要）
poetry publish

以前は twine という別ツールが必要でしたが、Poetry なら標準機能で完結します。

よく使う Poetry コマンドリファレンス

日常的な開発で頻繁に使用するコマンドをまとめました。

コマンド用途
poetry add [package]新しいパッケージを追加し、インストールする。
poetry installpoetry.lock を元に環境を構築する。
poetry update依存関係を最新に更新し、poetry.lock を書き換える。
poetry checkpyproject.toml の構造が正しいか検証する。
poetry config --list現在の Poetry の設定一覧を表示する。
poetry env info現在使用している仮想環境の情報を表示する。
poetry env use python3.x使用する Python のバージョンを切り替える。

Poetry を Docker で活用する際のコツ

モダンな開発では Docker と Poetry を併用する機会も多いでしょう。

Docker イメージをビルドする際、開発用ツール（pytestなど）を除外して軽量なイメージを作るための Dockerfile の書き方を紹介します。

Dockerfile
# Pythonのベースイメージを指定
FROM python:3.11-slim

# 作業ディレクトリの設定
WORKDIR /app

# Poetryのインストール
RUN pip install poetry

# 設定変更: 仮想環境を作らずにシステムに直接インストールする（コンテナ内なので安全）
RUN poetry config virtualenvs.create false

# 設定ファイルのみを先にコピー（キャッシュ効率化のため）
COPY pyproject.toml poetry.lock /app/

# 本番用依存関係のみをインストール (--without dev)
RUN poetry install --without dev --no-interaction --no-ansi

# ソースコードのコピー
COPY . /app/

# アプリケーションの実行
CMD ["python", "main.py"]

ポイントは poetry config virtualenvs.create false です。

Docker コンテナ自体が隔離された環境であるため、コンテナ内でさらに仮想環境を作る必要はなく、直接 Python 環境にパッケージをインストールすることで、実行時のパス指定などを簡略化できます。

トラブルシューティング：困ったときは

Poetry を使用していて遭遇しやすい問題とその対処法です。

依存関係の解決がいつまでも終わらない

特定のライブラリが非常に複雑な依存関係を持っている場合、解決に時間がかかることがあります。

この場合は、一度 poetry.lock を削除してから poetry lock を再実行するか、問題となっているライブラリのバージョンを pyproject.toml で明示的に固定してみてください。

Python バージョンの不一致

「The current project’s Python requirement (>=3.10,<4.0) is not compatible with some of the required packages Python requirement」といったエラーが出る場合、追加しようとしているライブラリが現在の Python バージョンをサポートしていない可能性があります。

この場合、pyproject.toml 内の python バージョン指定を見直すか、ライブラリの古いバージョンを指定してインストールを試みてください。

まとめ

Python Poetry は、これまでの煩雑だったパッケージ管理と環境構築を、クリーンで直感的なものへと進化させました。

「pyproject.toml による設定の一元管理」、「poetry.lock による厳密なバージョン固定」、そして 「仮想環境の自動ハンドリング」 という3つの柱により、開発者は環境のトラブルに悩まされることなく、本来のコーディング作業に集中できるようになります。

最初はコマンド操作に戸惑うかもしれませんが、一度使い始めれば、その便利さから従来の pip 管理に戻ることは難しくなるでしょう。

本記事を参考に、ぜひあなたのプロジェクトにも Poetry を導入し、モダンで快適な Python 開発ライフを手に入れてください。