はじめに
Python の依存管理ツールには pip、pipenv などがありますが、
2025 年現在 Poetry が最も安定・高速・実務向きと言われています。
- 依存管理
- 仮想環境管理
- ビルド
- パッケージ公開
これらをすべて一つで統合できる“現代型ツール”です。
本記事では、Poetry を インストール → 実務導入 → 運用 → 公開 まで一気に理解できるようにまとめました。
1. Poetry とは？
Poetry は Python の依存関係管理＋パッケージ管理を行うモダンツールです。
🔥 Poetry の特徴まとめ
- 依存関係の解決が高速で正確（pipenv より圧倒的に速い）
- 仮想環境を自動で作成・管理
- 環境を再現可能にする lockfile（poetry.lock）
- 設定ファイルは pyproject.toml のみ
- ライブラリ開発にも強く、パッケージ公開も簡単
- Beautiful な CLI（直感的なコマンド体系）
シンプルでありながら、プロダクション品質の依存管理がこれ 1 つで完結。
2. インストール
公式の推奨はインストーラ経由。
curl -sSL https://install.python-poetry.org | python3 -
PATH を通すため、必要なら以下も追加：
export PATH="$HOME/.local/bin:$PATH"
確認：
poetry --version
3. プロジェクト作成
新規プロジェクトを作る
poetry new myproject
構成イメージ：
myproject/
├── myproject/
│ └── __init__.py
├── tests/
├── pyproject.toml
└── README.md
4. 既存プロジェクトに導入
poetry init
依存を対話式で追加できます。
5. 依存ライブラリの追加
バージョン指定なし（自動で最新の安定版）
poetry add fastapi
バージョン指定
poetry add "uvicorn==0.29.0"
開発用
poetry add --dev black
Poetry は依存関係を解析して poetry.lock を生成します。
6. 仮想環境の扱い（Poetry が自動管理）
Poetry は依存追加時に自動で仮想環境を作ります。
シェルに入る
poetry shell
実行するだけなら
poetry run python main.py
仮想環境のパス確認
poetry env info
手動で再作成
poetry env remove python
poetry install
7. pyproject.toml の基本構造
Poetry はすべての設定を pyproject.toml に記述します。
[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "Sample project"
authors = ["Anna <anna@example.com>"]
[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.110.0"
uvicorn = "^0.29.0"
[tool.poetry.group.dev.dependencies]
black = "^24.3"
pytest = "^8.2"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
依存は toml の美しいシンタックスで管理
JSON のようにカンマで目が死なない。
8. poetry.lock とは？
- 依存関係、バージョン、ハッシュを 完全固定 するファイル
- “環境再現性”を担保
- CI、本番環境、チーム共同作業に必須
lock を更新
poetry lock
lockfile からインストール
poetry install
9. requirements.txt を出力したい場合
本番や Docker で必要になることが多い。
poetry export -f requirements.txt --output requirements.txt
ハッシュ付きで安全に：
poetry export -f requirements.txt --without-hashes > requirements.txt
10. スクリプト実行（CLI の代わりに登録できる）
pyproject.toml に登録しておけば：
[tool.poetry.scripts]
start = "myproject.main:run"
実行：
poetry run start
11. ビルドと配布（PyPI 公開）
ビルド
poetry build
dist/ に wheel と tar.gz が生成されます。
PyPI に公開
poetry publish
事前に token を設定するだけでOK。
12. 実務での Poetry の強み
依存解決が高速で賢い
pipenv や pip の手動管理と比較すると段違い。
lockfile による環境再現性が鉄壁
Docker、CI/CD、本番環境で強い。
pyproject.toml のシングルファイル管理
settings + build + dependencies が一元化。
ライブラリ開発にも対応
ビルド・公開までワンツール。
格段に使いやすい CLI
コマンド体系が直感的で覚えやすい。
13. Poetry が向いている人 / プロジェクト
| 種類 | 向いている理由 |
|---|---|
| 個人開発 | セットアップが速い |
| チーム開発 | lockfile で環境差分ゼロ |
| Web API 開発（FastAPI/Django） | 依存が多くても管理しやすい |
| ライブラリ開発 | 配布まで統合されている |
| Docker 運用 | requirements.txt エクスポートも簡単 |
まとめ
| 項目 | Poetry の評価 |
|---|---|
| 依存解決の速さ | ★★★★★ |
| 安定性 | ★★★★★ |
| 再現性 | ★★★★★ |
| 使いやすさ | ★★★★★ |
| 将来性 | ★★★★★（主流へ移行中） |
Poetry を使うと、Python 開発の世界が一段クリアになる。
「pip + venv 手動管理」では戻れない快適さがある。
これは、Python における“新しい標準のかたち”。