← package-managementツール一覧に戻る

Poetry

パッケージマネージャーPythonpyproject.toml仮想環境依存関係管理ロックファイルモダンPython

パッケージマネージャー

Poetry

概要

Poetryは、Pythonプロジェクトの依存関係管理とパッケージングを効率化するモダンなツールです。従来のpip、setuptools、requirements.txtの組み合わせに代わる統合ソリューションとして設計され、PEP 518準拠のpyproject.tomlファイルによる設定管理、決定論的なpoetry.lockファイル、自動仮想環境管理を提供します。2025年1月にリリースされたPoetry 2.0では、PEP 621準拠の[project]テーブルサポートが追加され、Pythonエコシステムの標準化がさらに進みました。

詳細

Poetryは2018年にSébastien Eustaceによって開発され、Pythonのパッケージ管理における複雑さを解決するために作られました。PEP 518で定義されたpyproject.tomlファイルを活用し、プロジェクトのメタデータ、依存関係、ビルド設定を一元管理します。決定論的なpoetry.lockファイルにより、すべての依存関係の正確なバージョンを記録し、異なる環境での再現可能なビルドを実現します。依存関係グループ機能により、開発・テスト・ドキュメントなど用途別の依存関係を分離管理でき、大規模プロジェクトでの保守性が向上します。また、自動仮想環境管理により、システム全体のPython環境を汚染することなく、プロジェクト独立の環境を維持できます。

メリット・デメリット

メリット

  • 統合された依存関係管理: pip、virtualenv、requirements.txtを一つのツールで置き換え
  • 決定論的ビルド: poetry.lockファイルによる正確なバージョン管理
  • 自動仮想環境管理: プロジェクト毎の分離された環境を自動作成・管理
  • PEP準拠: pyproject.toml（PEP 518）と[project]テーブル（PEP 621）をサポート
  • 依存関係グループ: 開発・テスト・本番環境の依存関係を分離管理
  • パッケージ公開: PyPIへの公開プロセスを簡略化
  • 高度な依存関係解決: 複雑な依存関係の競合を自動解決

デメリット

  • 学習コスト: pip/virtualenvからの移行時の概念理解が必要
  • パフォーマンス: 依存関係解決がPython実装のため、大規模プロジェクトで時間がかかる場合
  • メモリ使用量: 複雑な依存関係グラフでメモリ消費が増加
  • エコシステム互換性: 一部の古いツールとの互換性問題
  • 競合ツール: UV等のRust実装ツールと比較して速度面で劣る

参考ページ

書き方の例

基本的なプロジェクト管理

# Poetryのインストール
curl -sSL https://install.python-poetry.org | python3 -

# 新しいプロジェクトの作成
poetry new my-project
cd my-project

# 既存プロジェクトの初期化
poetry init

# 依存関係のインストール
poetry install

# パッケージの追加
poetry add requests
poetry add pytest --group dev
poetry add mkdocs --group docs

# パッケージの削除
poetry remove requests
poetry remove pytest --group dev

pyproject.toml設定（Poetry 2.0+）

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

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome Python project"
authors = [
    {name = "Your Name", email = "[email protected]"}
]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.28.0",
    "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=5.0.0",
]
docs = [
    "sphinx>=5.0.0",
    "sphinx-rtd-theme>=1.0.0",
]

[tool.poetry]
packages = [{include = "my_project"}]

# 従来のPoetry形式（Poetry 1.x互換）
[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"
click = "^8.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
black = "^22.0.0"
flake8 = "^5.0.0"

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
sphinx = "^5.0.0"
sphinx-rtd-theme = "^1.0.0"

依存関係グループの管理

# 特定グループの依存関係をインストール
poetry install --with docs
poetry install --with dev,docs

# 特定グループを除外してインストール
poetry install --without dev
poetry install --without dev,docs

# 特定グループのみインストール
poetry install --only dev
poetry install --only docs,test

# 同期インストール（lockファイルと完全一致）
poetry install --sync
poetry install --with docs --sync

# 本番環境向けインストール
poetry install --only main

仮想環境管理

# 仮想環境情報の表示
poetry env info
poetry env info --path

# 仮想環境の一覧表示
poetry env list

# 特定Pythonバージョンの仮想環境作成
poetry env use python3.11
poetry env use /usr/bin/python3.9
poetry env use system

# 仮想環境の削除
poetry env remove python3.11
poetry env remove --all

# 仮想環境内でコマンド実行
poetry run python main.py
poetry run pytest
poetry run black .

# 仮想環境のシェル起動
poetry shell

高度な依存関係指定

# Git リポジトリからの依存関係
poetry add git+https://github.com/user/repo.git
poetry add git+https://github.com/user/repo.git@branch
poetry add git+https://github.com/user/repo.git#subdirectory=subdir

# ローカルパスからの依存関係
poetry add ./local-package
poetry add ../shared-library --editable

# URL指定での依存関係
poetry add https://example.com/package.whl

# 複雑な条件指定
poetry add 'requests[security,socks]>=2.25.0,<3.0.0'
poetry add 'typing-extensions; python_version<"3.8"'

# バージョン制約の例
poetry add django~=4.1.0    # >=4.1.0, <4.2.0
poetry add numpy^=1.21.0    # >=1.21.0, <2.0.0
poetry add pytest@latest    # 最新版

パッケージ公開とビルド

# パッケージのビルド
poetry build

# PyPIトークンの設定
poetry config pypi-token.pypi your-api-token

# テストPyPIへの公開
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi

# 本番PyPIへの公開
poetry publish

# ドライランでの確認
poetry publish --dry-run

# ビルドと公開を同時実行
poetry publish --build

設定とカスタマイズ

# グローバル設定
poetry config virtualenvs.create true
poetry config virtualenvs.in-project true
poetry config virtualenvs.prefer-active-python true

# プロジェクト固有設定（poetry.toml）
poetry config virtualenvs.create false --local
poetry config repositories.private https://private.pypi.org/

# 設定の確認
poetry config --list
poetry config virtualenvs.path

# キャッシュ管理
poetry cache list
poetry cache clear pypi --all
poetry cache clear testpypi --all

# 環境変数での設定
export POETRY_VIRTUALENVS_IN_PROJECT=true
export POETRY_CACHE_DIR=/tmp/poetry-cache