Python Poetry：モダンな依存関係管理とパッケージングガイド

Name

Soren Atelier

Updated on 2026/2/12

Python の依存関係管理が苦痛である必要はありません。とはいえ、すべての Python 開発者が次のような状況を経験しています。プロジェクトを clone して pip install -r requirements.txt を実行すると、依存関係の衝突がターミナル上で連鎖的に発生する。パッケージ A はあるライブラリの 1.x を必要とし、パッケージ B は 2.x を必要とし、pip は最後に解決したほうを（静かに）インストールして、どちらかを壊してしまう。結果、デバッグに何時間も溶けます。原因は、pip に適切な依存関係解決とロックファイル機構が欠けていることです。

この問題はチーム環境でさらに悪化します。ある開発者は厳密なバージョンを pin し、別の開発者は緩い範囲指定を使い、さらに別の開発者は新しいパッケージを入れたのに requirements.txt を更新し忘れる。デプロイが失敗し、ローカルではテストが通るのに CI では壊れる。根本原因はいつも同じで、Python の標準ツール群が依存関係管理を後回しにしていることです。

Poetry は、依存関係解決、仮想環境管理、パッケージ公開を 1 つのツールで扱うことでこれを解決します。標準化された pyproject.toml を使い、決定論的なロックファイルを生成し、インストール後ではなくインストール前に依存関係の衝突を解決します。このガイドでは、インストールから公開まで、あらゆるワークフローを実例付きで解説します。

Python Poetry とは？

Poetry は、Python 向けのオープンソースな依存関係管理・パッケージングツールです。2018 年に Sebastien Eustace によって作られ、断片化していた Python のパッケージング状況に対して、複数の機能を 1 つの統一されたツールにまとめて提供します。

• 依存関係解決：Poetry は依存関係とそのサブ依存関係をすべて解析し、互換性のあるバージョン集合を、何もインストールする前に見つけます。
• ロックファイル：poetry.lock がインストールされた全パッケージの正確なバージョンを記録し、マシン間で再現可能なビルドを保証します。
• 仮想環境管理：Poetry はプロジェクトごとに隔離された仮想環境を自動作成・管理します。
• パッケージのビルドと公開：ソースディストリビューションと wheel をビルドし、PyPI やプライベートリポジトリに直接公開できます。
• プロジェクト雛形生成：適切な pyproject.toml 設定を含むプロジェクト構成を生成します。

Poetry は設定ファイルとして pyproject.toml を使用し、PEP 518 と PEP 621 に準拠します。これにより、従来の Python プロジェクトで必要だった setup.py、setup.cfg、requirements.txt、MANIFEST.in の組み合わせを置き換えられます。

Poetry のインストール

Poetry は独自のインストーラを提供しており、プロジェクト依存関係から隔離してインストールできます。これにより、Poetry 自体とプロジェクトのパッケージ間のバージョン衝突を防ぎます。

推奨インストール（公式インストーラ）

Linux、macOS、Windows（WSL）：

curl -sSL https://install.python-poetry.org | python3 -

Windows（PowerShell）：

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

インストール後、Poetry を PATH に追加します。インストーラが正確なパスを表示します（Linux/macOS では通常 $HOME/.local/bin、Windows では %APPDATA%\Python\Scripts）。

インストール確認：

poetry --version

pipx でのインストール

pipx（CLI ツールを隔離して管理）を使いたい場合：

pipx install poetry

Poetry のアップデート

poetry self update

特定バージョンへアップデート：

poetry self update 1.8.0

タブ補完の有効化

Poetry は Bash、Zsh、Fish の補完に対応しています。

# Bash
poetry completions bash >> ~/.bash_completion
 
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
 
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

新しいプロジェクトの作成

Poetry には、ゼロから新規作成する方法と、既存プロジェクトに Poetry を初期化する方法の 2 つがあります。

ゼロから新規作成

poetry new my-project

次の構成が生成されます。

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

フラットなソースレイアウト（パッケージがルートにある構成）にする場合：

poetry new --src my-project

src/ ディレクトリ配下に配置されます。

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

既存プロジェクトで初期化

既存プロジェクトのディレクトリへ移動して実行します。

cd existing-project
poetry init

Poetry が対話形式でセットアップを進め、パッケージ名、バージョン、説明、作者、Python バージョン互換性、依存関係などを尋ねます。Enter でデフォルト採用、任意項目はスキップできます。

非対話形式で行う場合：

poetry init --name my-package --description "A useful package" --author "Your Name <you@example.com>" --python "^3.9" --no-interaction

pyproject.toml を理解する

pyproject.toml はプロジェクト設定の「単一の信頼できる情報源（single source of truth）」です。完全な例は次のとおりです。

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = "A data processing library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/yourname/my-project"
repository = "https://github.com/yourname/my-project"
keywords = ["data", "processing", "analytics"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries",
]
 
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.31"
pydantic = ">=2.0,<3.0"
 
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.0"
ruff = "^0.3"
 
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
sphinx-rtd-theme = "^2.0"
 
[tool.poetry.scripts]
my-cli = "my_project.cli:main"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

バージョン制約の書式

Poetry は分かりやすいバージョン制約構文を採用しています。

キャレット（^）制約は最も一般的で推奨されます。セマンティックバージョニングの原則に従い、「左端の 0 以外の数字」を変えない範囲での更新を許可します。

依存関係グループ

Poetry は依存関係をグループ化でき、requirements ファイルを分ける必要を減らせます。

• メイン依存関係（[tool.poetry.dependencies]）：パッケージが動作するために必要。利用者がインストールする際に含まれます。
• 開発依存関係（[tool.poetry.group.dev.dependencies]）：開発・テスト・lint 用。公開パッケージには含まれません。
• カスタムグループ（[tool.poetry.group.docs.dependencies]）：ドキュメント用など、用途に応じて追加できます。

依存関係の追加と削除

パッケージの追加

メイン依存関係に追加：

poetry add pandas

バージョン制約付きで追加：

poetry add "pandas>=2.0,<3.0"

開発グループへ追加：

poetry add --group dev pytest black ruff

カスタムグループへ追加：

poetry add --group docs sphinx

Git リポジトリから追加：

poetry add git+https://github.com/user/repo.git

特定ブランチやタグから追加：

poetry add git+https://github.com/user/repo.git#branch-name
poetry add git+https://github.com/user/repo.git#v1.0.0

ローカルパス依存として追加：

poetry add ../my-local-package

extras を指定して追加：

poetry add "uvicorn[standard]"

パッケージの削除

削除：

poetry remove pandas

特定グループから削除：

poetry remove --group dev black

インストール済みパッケージの一覧

全パッケージ表示：

poetry show

特定パッケージの詳細：

poetry show pandas

依存関係ツリー表示：

poetry show --tree

古いパッケージ表示：

poetry show --outdated

ロックファイル：poetry.lock

poetry.lock は Poetry の最重要機能の 1 つです。poetry install または poetry add を実行すると、Poetry は依存関係を解決し、（推移的依存関係を含む）正確なバージョンを poetry.lock に書き込みます。

ロックファイルが重要な理由

ロックファイルがないと、requirements.txt に緩いバージョン制約が書かれている場合、pip install -r requirements.txt の結果がマシンや実行時期によって変わり得ます。ロックファイルはこの不確実性を排除します。

例：

[tool.poetry.dependencies]
requests = "^2.28"

これは 2.28.0 から 2.99.x までを許容します。ロックファイルがなければ、CI は 2.31.0 を入れ、ローカルは 2.28.2 のまま、といった差が発生します。ロックファイルは全環境で厳密なバージョンを固定します。

ロックファイル運用

poetry.lock をバージョン管理にコミットする。 これにより、すべての開発者・デプロイが同一バージョンを使用します。

git add poetry.lock pyproject.toml
git commit -m "Add project dependencies"

ロックファイルからインストール（再現可能インストール）：

poetry install

poetry.lock にあるバージョンを厳密に入れ、新しい互換バージョンがあっても無視します。

新しいバージョンが欲しいときにロックファイルを更新：

# 全パッケージを更新
poetry update
 
# 特定パッケージを更新
poetry update pandas
 
# インストールせずロックだけ更新
poetry lock

ロックファイル整合性の検証：

poetry lock --check

pyproject.toml と整合しているかを、変更せずに確認します。

仮想環境管理

Poetry はプロジェクトの仮想環境を自動作成・管理します。

デフォルト挙動

poetry install や poetry add を実行すると、環境がなければ作成します。デフォルトでは仮想環境は集中キャッシュに保存されます。

• Linux: ~/.cache/pypoetry/virtualenvs/
• macOS: ~/Library/Caches/pypoetry/virtualenvs/
• Windows: C:\Users\<user>\AppData\Local\pypoetry\Cache\virtualenvs\

プロジェクト内仮想環境

多くの開発者は、プロジェクトディレクトリ内に仮想環境を置く（Node.js の node_modules に近い）方を好みます。これをグローバル設定できます。

poetry config virtualenvs.in-project true

プロジェクトルートに .venv が作られ、場所が分かりやすく IDE の自動検出とも相性が良いです。

仮想環境内でコマンド実行

単発コマンドを実行：

poetry run python my_script.py
poetry run pytest
poetry run black .

環境シェルを起動：

poetry shell

仮想環境が有効化された新しいシェルが起動します。exit または Ctrl+D で終了します。

環境情報

環境の詳細：

poetry env info

プロジェクトに紐づく環境一覧：

poetry env list

特定の Python バージョンを使う：

poetry env use python3.11

環境を削除：

poetry env remove python3.11

依存関係のインストール

標準インストール

依存関係（main と dev）をすべてインストール：

poetry install

本番用インストール

開発依存を除外：

poetry install --without dev

特定グループを除外：

poetry install --without dev,docs

特定グループだけをインストール

poetry install --only main
poetry install --only dev

環境の同期

ロックファイルにないパッケージを削除（クリーンな状態に合わせる）：

poetry install --sync

手動で入れたパッケージや、ロックから消えたパッケージを削除し、環境をプロジェクト設定と厳密に一致させます。

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

Poetry は公開までのワークフローをシンプルにします。

パッケージのビルド

poetry build

dist/ に sdist（.tar.gz）と wheel（.whl）が作成されます。

dist/
├── my_project-1.0.0.tar.gz
└── my_project-1.0.0-py3-none-any.whl

PyPI への公開

まず PyPI 認証情報を設定：

poetry config pypi-token.pypi your-api-token

公開：

poetry publish --build

--build はビルドと公開を 1 ステップで行います。

プライベートリポジトリへの公開

プライベートリポジトリを追加：

poetry config repositories.private https://private.pypi.example.com/simple/
poetry config http-basic.private username password

公開：

poetry publish --repository private

バージョン管理

セマンティックバージョニングに従って bump：

poetry version patch    # 1.0.0 -> 1.0.1
poetry version minor    # 1.0.0 -> 1.1.0
poetry version major    # 1.0.0 -> 2.0.0
poetry version prepatch # 1.0.0 -> 1.0.1a0

現在のバージョン表示：

poetry version

requirements.txt からの移行

既存プロジェクトが requirements.txt を使っていても、Poetry への移行は簡単です。

Step 1: Poetry を初期化

cd your-project
poetry init --no-interaction

Step 2: requirements.txt から依存関係を追加

単純な requirements ファイルの場合：

cat requirements.txt | xargs poetry add

バージョン制約がある場合は、手作業で追加するか移行スクリプトを使います。

import subprocess
 
with open("requirements.txt") as f:
    packages = []
    for line in f:
        line = line.strip()
        if line and not line.startswith("#") and not line.startswith("-"):
            packages.append(line)
 
if packages:
    subprocess.run(["poetry", "add"] + packages)

Step 3: 開発依存関係を追加

requirements-dev.txt がある場合：

cat requirements-dev.txt | xargs poetry add --group dev

Step 4: 検証とロック

poetry install
poetry lock --check

Step 5: 後片付け

動作確認後、古いファイルを削除できます。

rm requirements.txt requirements-dev.txt setup.py setup.cfg

requirements.txt へのエクスポート（戻し）

互換性のために requirements.txt が必要な場合（Docker ビルドやレガシー CI など）：

poetry export -f requirements.txt --output requirements.txt

開発依存も含める：

poetry export -f requirements.txt --with dev --output requirements-dev.txt

Poetry vs pip vs pipenv vs uv：比較

適切な依存関係管理ツールの選択は、プロジェクト要件によります。以下に詳細な比較を示します。

どのツールを選ぶべきか

Poetry を選ぶ：依存関係管理、ビルド、PyPI 公開までを 1 つのツールで完結させたい場合。成熟したエコシステムと豊富なドキュメントがあります。

pip を選ぶ：単純なスクリプトや素早い試作、標準ツール縛りがある環境。pip は他ツールの土台でもあります。

pipenv を選ぶ：再現可能な環境は必要だが PyPI に公開はしない Web アプリ開発など。Pipfile で開発/本番依存を明確に分離できます。

uv を選ぶ：インストール速度が最優先、または Python バージョンも単一ツールで管理したい場合。Rust 製で依存関係解決が高速で、pip 互換のため置き換えもしやすいです。

Poetry の設定とヒント

便利な設定オプション

# 仮想環境をプロジェクトディレクトリ内に保存
poetry config virtualenvs.in-project true
 
# 新規環境作成時に特定の Python を優先
poetry config virtualenvs.prefer-active-python true
 
# 仮想環境の自動作成を無効化
poetry config virtualenvs.create false
 
# 全設定を表示
poetry config --list

Docker で Poetry を使う

Poetry を使った本番用 Dockerfile 例：

FROM python:3.12-slim
 
ENV POETRY_VERSION=1.8.0 \
    POETRY_HOME="/opt/poetry" \
    POETRY_VIRTUALENVS_CREATE=false \
    POETRY_NO_INTERACTION=1
 
RUN pip install poetry==$POETRY_VERSION
 
WORKDIR /app
 
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
 
COPY . .
RUN poetry install --without dev
 
CMD ["python", "-m", "my_project"]

ポイント：

• POETRY_VIRTUALENVS_CREATE=false により、コンテナ内での仮想環境作成をスキップ（コンテナ自体が隔離を提供）。
• ソースコードより先に依存関係をインストールして Docker レイヤキャッシュを効かせる。
• poetry install を 2 回実行：最初は依存関係のみ（--no-root）、次にプロジェクト自体もインストール。

CI/CD で Poetry を使う

GitHub Actions 例：

name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install Poetry
        run: pip install poetry
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest
      - name: Run linting
        run: poetry run ruff check .

Jupyter ワークフローで Poetry を使う

Jupyter notebook を使うデータサイエンスでは依存関係管理が特に重要です。Poetry を使うことで、notebook が正しい環境を参照するようにできます。

Poetry プロジェクト内に Jupyter をインストール：

poetry add --group dev jupyter ipykernel

Poetry 環境を Jupyter kernel として登録：

poetry run python -m ipykernel install --user --name=my-project

Poetry 環境内で Jupyter を起動：

poetry run jupyter notebook

依存関係管理の自動化と AI 支援を備えた、よりスムーズな Jupyter 体験のために、RunCell (opens in a new tab) は分析に集中できる統合環境を提供します。RunCell はパッケージインストールと kernel 管理を自動で扱い、Poetry のプロジェクト単位の依存関係制御を補完します。

よく使う Poetry コマンド一覧

よくある問題のトラブルシューティング

依存関係解決の失敗

問題：互換性のあるバージョン集合が見つからない。

SolverProblemError: ...unable to find compatible versions...

解決：バージョン制約を緩めるか、衝突する要件を確認します。

# 競合の内容を確認
poetry show --tree
 
# より広い制約で試す
poetry add "problematic-package>=1.0"

解決が遅い

問題：poetry lock に時間がかかる。

解決：Poetry はパッケージメタデータをキャッシュしますが、依存関係が多いプロジェクトの初回解決は遅くなりがちです。数分以上かかる場合：

# キャッシュを消して再試行
poetry cache clear --all pypi
 
# verbose で状況確認
poetry lock -vvv

IDE が仮想環境を検出しない

問題：VS Code や PyCharm が Poetry の環境を見つけない。

解決：プロジェクト内仮想環境を有効化します。

poetry config virtualenvs.in-project true
poetry install  # プロジェクトルートに .venv を再作成

その後 IDE で .venv/bin/python を interpreter に選択してください。

Hash 不一致エラー

問題：poetry install で hash mismatch が報告される。

解決：ロックファイルを再生成します。

poetry lock --no-update

依存関係バージョンは変えずに hash を再生成します。

FAQ

Python Poetry は何に使いますか？

Python Poetry は、パッケージのインストール、バージョン衝突の解決、仮想環境の管理、PyPI への公開を扱う依存関係管理・パッケージングツールです。pyproject.toml を中心にした統一ツールとして、pip、venv、setuptools、twine の組み合わせを置き換えます。

Poetry は pip より優れていますか？

Poetry と pip は目的が異なります。Poetry は依存関係解決、ロックファイル、仮想環境管理、パッケージ公開を 1 つのツールで提供します。pip はよりシンプルで、単純なインストールに向きます。再現可能ビルド、チーム開発、パッケージ公開が必要なら Poetry の利点は大きく、短いスクリプトや小規模用途なら pip でも十分です。

pip から Poetry へ切り替えるには？

poetry init でプロジェクトを初期化し、cat requirements.txt | xargs poetry add で requirements.txt から依存関係を追加します。Poetry は pyproject.toml と poetry.lock を作成します。poetry install で動作確認後、古い requirements.txt を削除できます。互換性のために必要なら poetry export を使って requirements.txt を出力できます。

Poetry は virtualenv の代わりになりますか？

はい。Poetry はプロジェクトごとに仮想環境を自動作成・管理するため、手動で作成・有効化する必要はありません。デフォルトでは集中キャッシュに保存しますが、poetry config virtualenvs.in-project true でプロジェクト内に置くこともできます。対話的に使いたい場合は poetry shell で有効化できます。

Poetry は複数の Python バージョンを管理できますか？

Poetry 自体は Python をインストールしませんが、システムに存在する Python を利用できます。pyenv や uv で複数バージョンを入れ、poetry env use python3.11 のように指定します。同一プロジェクトでも Python バージョンごとに別の仮想環境が作られます。

poetry.lock と requirements.txt の違いは？

poetry.lock は、推移的依存関係を含む全パッケージの正確なバージョンと、検証用のコンテンツ hash を記録します。pip freeze で生成した requirements.txt も正確なバージョンを列挙しますが、hash 検証や依存関係の関係性トラッキングがありません。ロックファイルは全環境で決定論的なインストールを保証します。一方 requirements.txt は推移的依存関係が更新されると結果が変わり得ます。

結論

Python Poetry は、摩擦の原因になりがちな依存関係管理を、整理されたワークフローへ変えてくれます。依存関係解決、仮想環境管理、パッケージ公開を 1 つのツールに統合することで、長年 Python 開発者を悩ませてきた断片的なツールチェーンを解消します。pyproject.toml は単一の信頼できる情報源として機能し、ロックファイルは再現可能なインストールを保証し、依存関係解決器は実行時障害になる前に衝突を検知します。

PyPI 向けライブラリを作る場合でも、依存関係が数十に及ぶ複雑なアプリケーションを管理する場合でも、環境の一貫性が必要なチーム開発でも、Poetry は pip 単体では得られない構造と信頼性を提供します。学習コストも大きくはなく、多くの開発者は 1 時間以内に実用レベルに到達できます。依存関係デバッグに費やしていた時間が減るだけで、最初の 1 週間で元が取れるはずです。

次のプロジェクトでは poetry new を、既存プロジェクトでは poetry init をまず試してください。依存関係を追加し、ロックファイルをコミットし、「あるべき姿で動く」依存関係管理を体験しましょう。Jupyter を使うデータサイエンス用途では、Poetry のプロジェクト単位の依存関係制御に RunCell (opens in a new tab) を組み合わせることで、パッケージ管理と対話的分析の両方をシームレスに扱える環境になります。