Zenn
🐍

Poetry入門：Python仮想環境と依存管理の最短コース

に公開
Python
CLI
仮想環境
poetry
pyproject
tech

Poetry入門：Python仮想環境と依存管理の最短コース

はじめに

Python を使った開発を始めようとすると、「依存パッケージをどう管理する？」「仮想環境はどうやって作る？」「スクリプトをコマンドとして実行したいけど、どうすれば？」といった悩みに直面します。

そんな時に役立つのが Poetry です。Poetryは、Pythonの仮想環境の作成から依存パッケージの管理、さらにはCLIツールとしての配布までを一貫して扱える便利なツールです。

このチートシートでは、Poetryのインストール方法から、実際のプロジェクト構成、テスト、CLI化までを、初心者にも分かりやすく紹介します。

Poetryとは？

Poetryは、Pythonの依存関係と仮想環境をまとめて管理できるツールです。

  • requirements.txt の代わりに pyproject.toml で依存管理
  • venv の作成・削除も自動
  • setup.py なしでCLIツールの配布も可能

始め方（3分で完了）

Poetryのインストール（ユーザー環境のみ）

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

Poetryは $HOME/.local/bin にインストールされます。
もしPATHが通っていない場合は、以下を追記：

export PATH="$HOME/.local/bin:$PATH"

Appendix: pipx 経由でPoetryをインストールする

Poetryのようなツールをグローバルにインストールする場合、pipx を使うと他の環境を汚さず便利です。

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install poetry

複数ツール（例：black, pre-commitなど）を requirements.txt に列挙しておき、まとめてインストールできます：

poetry
black
pre-commit

xargs -n 1 pipx install < requirements.txt

このコマンドは、requirements.txt に書かれた各行を1つずつ pipx install に渡して実行するものです。

プロジェクトの作成と実行

# 新しいプロジェクトを作成
poetry new mytool
cd mytool

# 依存関係のインストール（仮想環境も自動作成）
poetry install

# 簡単な動作確認
poetry run python mytool/__init__.py

Poetry コマンドチートシート

作業内容 コマンド
依存関係の追加 poetry add requests
開発用依存の追加 poetry add --group dev pytest
仮想環境に入る poetry shell
仮想環境から出る exit
仮想環境のパス確認 poetry env info --path
仮想環境の削除 poetry env remove python
パッケージの更新 poetry update
スクリプトの実行 poetry run python script.py
CLI化したコマンドの実行 poetry run hello

開発専用パッケージの追加（pytestの例）

開発時にのみ必要なツール（例：pytest）は、次のようにして追加します：

poetry add --group dev pytest

テストの実行：

poetry run pytest

典型的なPoetryプロジェクト構成例

以下のような構成にすると、CLI、モジュール、テストが明確に分離され、拡張性の高いプロジェクトになります。

mytool/
├── pyproject.toml
├── README.md
├── src/
│   └── mytool/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       └── core.py
└── tests/
    └── test_core.py
  • cli.py: CLIのエントリポイント（argparseやclickなど）
  • core.py: ビジネスロジックやユーティリティ関数を定義
  • __main__.py: python -m mytool で実行されるスクリプト
  • tests/test_core.py: pytestでコア機能をテスト

pyproject.toml に packages = [{ include = "mytool", from = "src" }] を追記し、パス解決とビルド設定を整えることを忘れずに。

init.py の役割について

__init__.py は、Python においてそのディレクトリを「パッケージ」として認識させるためのファイルです。
このファイルが存在することで、ディレクトリをモジュールとしてインポートできるようになります。

たとえば src/mytool/ に __init__.py があれば、import mytool.core のように他のモジュールから使用できます。
中身が空でも構いませんが、__all__ や初期化処理を記述することもできます。

main.py の役割について

__main__.py は、モジュールを python -m パッケージ名 という形式で実行したときに呼び出されるエントリポイントです。

たとえば src/mytool/__main__.py に以下のように記述しておくと：

from mytool.cli import main

if __name__ == "__main__":
    main()

次のようにしてプロジェクトを実行できます：

poetry run python -m mytool

これにより、mytool パッケージをスクリプトとして扱うことができ、CLIとしての自然なインターフェースを提供できます。

core.py / test_core.py の簡単な例

src/mytool/core.py 

def add(a, b):
    return a + b

tests/test_core.py 

from mytool.core import add

def test_add():
    assert add(2, 3) == 5

poetry run pytest でテストを実行できます。

pyproject.toml の具体例（注釈付き）

[tool.poetry]
name = "mytool"
version = "0.1.0"
description = "A sample CLI tool built with Poetry"
authors = ["Your Name <you@example.com>"]
packages = [{ include = "mytool", from = "src" }]  # src/ 配下を明示

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.31"  # 任意の依存パッケージ

[tool.poetry.scripts]
mytool = "mytool.cli:main"  # CLIエントリポイント

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"  # 開発用依存

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

PoetryによるCLI化（[tool.poetry.scripts]の例）

pyproject.toml に以下を追加すると、poetry run でCLIのように実行できます：

[tool.poetry.scripts]
hello = "mytool.hello:main"

そして mytool/hello.py に次のように記述：

def main():
    print("Hello from CLI!")

実行コマンド：

poetry run hello

シェルスクリプトから Poetry を実行する例

run.sh:

#!/bin/bash
poetry run python mytool/hello.py

実行権限を付与：

chmod +x run.sh
./run.sh

このように、Poetryの仮想環境に自動的に入ってコマンドを実行できます。

よくある質問（FAQ）

Q. pyenv は必要ですか？

→ 不要です。システムに目的の Python バージョン（例：3.9）が入っていればOKです。

Q. 仮想環境はどこに作られますか？

→ デフォルトでは $HOME/.cache/pypoetry/virtualenvs/ に作成されます。

→ .venv/ に作りたい場合は次のコマンド：

poetry config virtualenvs.in-project true

おわりに

Poetryを使えば、Python開発の環境構築はずっと簡単になります。

  • 仮想環境の作成と管理
  • 依存パッケージの整理
  • CLIツールの実行・公開

これらをまとめて管理できるのはPoetryならでは。まずは一度試してみましょう。

著作と再利用に関する方針

本記事は、sisiodos による調査・整理・構成に基づき執筆されたものです。

内容はMITライセンスのもとに公開しており、再利用・改変・再配布は自由に行っていただけます。

ただし、引用・教育・AI生成などに取り込む際には、次のようなクレジットを添えていただけると嬉しく思います：

  • クレジット例：
    Poetry入門：Python仮想環境と依存管理の最短コース（sisiodos著）

本記事は、**「再利用されるための知識設計」**を意図しています。
教育・普及・応用・再構成の用途において、自由な展開と文化的な尊重の両立が行われることを願っています。

Discussion