パッケージ管理したい（poetry）

// 新規プロジェクト作成
$ poetry new my-project
$ cd my-project

// 依存関係の管理
$ poetry add requests pandas
$ poetry add --group dev pytest ruff ipykernel
$ poetry add --group docs sphinx

// 環境をセットアップ
$ poetry install

// スクリプトを実行
$ poetry run python main.py
$ poetry run pytest

// パッケージをビルド・公開
$ poetry build
$ poetry publish

poetryはPythonの依存関係管理、パッケージングを統合したツールです。 pyproject.tomlとpoetry.lockで依存関係を管理し、 仮想環境の構築、テスト実行、パッケージ公開までがシームレスに行えます。

注釈

poetryは複数の役割を統合しています：

• pipとvenv：パッケージ管理と仮想環境

• setuptools：パッケージビルド

• twine：パッケージ公開

すべてが1つのツールで完結するため、環境構築が簡単です。

インストールしたい（poetry）

$ pipx install poetry
Installing poetry (version 2.2.1)
Successfully installed poetry

$ poetry --version
Poetry (version 2.2.1)

公式ドキュメントではpipxを使ったインストールが推奨されています。

新規プロジェクトしたい（poetry new）

$ poetry new PROJECT_NAME
Created package project_name in PROJECT_NAME

$ tree -a PROJECT_NAME
PROJECT_NAME
├── README.md
├── project_name
│   └── __init__.py
├── pyproject.toml
└── tests
    └── __init__.py

$ poetry new PROJECT_NAME
Destination ./PROJECT_NAME exists and is not empty

newコマンドでプロジェクトを初期化できます。 テスト関係のファイルも自動で生成されます。 同名のプロジェクトがすでに存在する場合は、エラーになります プロジェクト名を省略した場合は、エラーになります。

既存プロジェクトを使いたい（poetry init）

$ cd プロジェクト名
$ poetry init

initコマンドで、既存のプロジェクトを初期化できます。 プロンプトの表示にしたがってプロジェクト情報（プロジェクト名、説明、作成者、バージョン番号、ライセンスなど）を入力します。 続けて、必要なパッケージに関するプロンプトが表示されるので、パッケージ名やバージョン番号を入力して、パッケージを選択します。 これらの設定はすべてpyproject.tomlの[tool.poetry]セクションに保存されます。 あとから直接編集できるので、間違えてしまっても大丈夫です。

パッケージを追加したい（poetry add）

$ poetry add requests pandas
$ poetry add --group dev pytest ruff
$ poetry add --group docs sphinx

poetry addコマンドで、プロジェクトに必要なパッケージを追加します。パッケージを追加すると、pyproject.tomlに記録され、poetry.lockが自動で生成・更新されます。

Tip

パッケージの追加先：

• poetry add requests - 本番環境（[tool.poetry.dependencies]）に追加

• poetry add --group dev pytest - 開発環境（[tool.poetry.group.dev.dependencies]）に追加

• poetry add --group docs sphinx - ドキュメント環境に追加

開発環境でのみ使うパッケージを追加したい

$ poetry add --group dev pytest black ruff jupyterlab

テストやコード整形など、開発時にのみ必要なパッケージは--group devオプションで追加します。本番環境にはインストールされません。

注釈

Poetry v1.3.0以降では、--groupを使ったグループ化が標準です。以前の-Dオプションは非推奨になりました。

ドキュメント環境でのみ使うパッケージを追加したい

$ poetry add --group docs sphinx sphinx_book_theme myst_parser

Sphinxなどドキュメント作成専用のパッケージは--group docsで追加します。これにより、必要な環境だけに必要なパッケージをインストールできます。

パッケージをインストールしたい（poetry install）

$ poetry install
Creating virtualenv poetry-xx in .venv
Installing dependencies from lock file
...

poetry installコマンドで、poetry.lockに記録されたすべてのパッケージをインストールして、仮想環境をセットアップします。poetry.lockがない場合は、pyproject.tomlから自動で生成されます。

Tip

初回セットアップの流れ：

1. poetry newやpoetry initでプロジェクトを初期化

2. poetry addでパッケージを追加

3. poetry installで仮想環境を構築

4. poetry runでコマンドを実行

デフォルトではPoetryキャッシュ内に仮想環境が作成されます。プロジェクト内に.venvを作成したい場合は、プロジェクト内に仮想環境を作成したいを参照してください。

スクリプトを実行したい（poetry run）

$ poetry run python main.py
# スクリプトが実行される

$ poetry run pytest
# テストが実行される

$ poetry run black .
# コード整形が実行される

poetry runコマンドで、セットアップした仮想環境内でコマンドを実行します。これにより、プロジェクトの依存関係が正確に反映された環境でスクリプトが動作します。

パッケージ環境を確認したい（poetry check）

$ poetry check
All set!

poetry checkでプロジェクトの設定が正しいか確認できます。--lockオプションでpoetry.lockの整合性も検証します。

パッケージをビルドしたい（poetry build）

$ poetry build
Building パッケージ名 (バージョン番号)
  - Building sdist
  - Built パッケージ名-バージョン番号.tar.gz
  - Building wheel
  - Built パッケージ名-バージョン番号-py3-none-any.whl

buildコマンドでパッケージをビルドできます。

パッケージを公開したい（poetry publish）

$ poetry publish -r testpypi
Publishing my_project (0.1.0) to testpypi
 - Uploading my_project-0.1.0-py3-none-any.whl
 - Uploading my_project-0.1.0.tar.gz

poetry publishでパッケージをPyPIに公開します。はじめて公開する場合は、必ずTestPyPIでテストしてから本番のPyPIに公開してください。事前にリポジトリとAPIトークンの設定が必要です。

参考

詳しい公開手順については、僕のZennスクラップ「poetryを使ってpythonパッケージを作成する」を参照してください。

TestPyPI／PyPIを設定したい

$ poetry config repositories.testpypi https://test.pypi.org/legacy/
$ poetry config pypi-token.testpypi <your-token>
$ poetry config pypi-token.pypi <your-token>
# 設定が保存される

TestPyPIとPyPIに公開するために、リポジトリURLとAPIトークンを設定します。APIトークンはそれぞれのサービスの個人ページで発行して、コマンドで登録してください。

PyPIはデフォルトの公開先なので、リポジトリのURL設定は不要です。TestPyPIのみ設定が必要です。

他にもプライベートリポジトリなど、さまざまな公開先を設定できます。詳細はRepositoriesを参照してください。

設定を管理したい

現在の設定を確認したい（poetry config --list）

$ poetry config --list
cache-dir = "~/Library/Caches/pypoetry"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.path = "{cache-dir}/virtualenvs"

poetry config --listで現在のPoetry設定をすべて表示します。デフォルト設定の詳細はPoetryドキュメントのAvailable Settingsを参照してください。

設定を変更したい

$ poetry config キー名 値
$ poetry config キー名 値 --local
# 設定が更新される

設定値を変更します。--localをつけるとプロジェクト内のpoetry.tomlに保存され、全体設定は~/Library/Application Support/pypoetry/config.tomlに保存されます。

設定を削除したい

$ poetry config キー名 --unset
# 設定が削除される

追加した設定を削除する場合は--unsetオプションを使います。

プロジェクト内に仮想環境を作成したい

$ poetry config virtualenvs.in-project true
$ poetry install
$ ls -la
.venv/

デフォルトではPoetryキャッシュ内に仮想環境が作成されますが、virtualenvs.in-project = trueに設定すると、プロジェクト内に.venvが作成されます。

GitHubやGitLabなどでチーム開発する場合、プロジェクト内に仮想環境があると管理しやすくなります。

注意

すでにキャッシュ内に仮想環境がある場合は、新しい設定でpoetry installする前に古い環境を削除してください。

システムのPythonパッケージを使いたい

$ poetry config virtualenvs.options.system-site-packages true
# 設定が更新される

virtualenvs.options.system-site-packages = trueに設定すると、システムのPython（site-packages）にインストールされたパッケージを仮想環境から利用できます。

複数のプロジェクトで共有する開発ツール（pytest、blackなど）を節約したい場合に有効です。

リファレンス

• Poetry