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

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

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

// 依存関係のインストール
$ poetry install
$ poetry sync

// パッケージの実行とテスト
$ poetry run python main.py
$ poetry run pytest

// パッケージ公開
$ poetry build
$ poetry publish

poetryは、Pythonの依存関係管理とパッケージングを統合したツールです。プロジェクトの初期化、依存関係の管理、仮想環境の作成、スクリプトの実行、パッケージのビルドと公開など、Pythonプロジェクトのあらゆる側面を管理できます。

pyproject.tomlとpoetry.lockを軸に、依存関係の再現性を保ちます。

注釈

Pythonでは、パッケージ管理にはpip、バージョン管理にはpyenv、プロジェクト管理にはpoetry のように、複数のツールがまるで戦国時代のように群雄割拠しています。

poetryは、その中でも早くからプロジェクト管理を統合的に提供してきたツールです。最近では、Rust製で高速なuvが同じ立ち位置で急速に普及していますが、 poetryは長く使われてきた実績があり、エコシステムも安定しています。

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

// pipxでインストール
$ pipx install poetry

$ which -a poetry
~/.local/bin/poetry

$ poetry --version
Poetry (version 2.4.1)

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

注釈

uvがインストール済みであれば、uv tool install poetryでもインストールできます。挙動はpipx install poetryとほぼ同じで、どちらも専用の仮想環境を作ってから、実行コマンドを~/.local/bin/にリンクします。

新規プロジェクトしたい（`poetry new` / `poetry init`）

poetryには、プロジェクトを作成する方法が2つあります。まっさらな状態から作る場合はpoetry new、既存のディレクトリにpyproject.tomlだけ追加したい場合はpoetry initを使います。

まっさらから作りたい（`poetry new`）

$ poetry new my-project
Created package my_project in my-project

$ find my-project -type f | grep -v .git
my-project/pyproject.toml
my-project/README.md
my-project/src/my_project/__init__.py
my-project/tests/__init__.py

poetry newコマンドで、新規プロジェクトを作成できます。 src/<パッケージ名>/レイアウトと、テスト用のtests/ディレクトリが自動生成されます。

$ poetry new my-project
Created package my_project in my-project

$ poetry new my-project
[tomlkit.exceptions.ParseError]
Destination my-project exists and is not empty

同名のディレクトリがすでに存在し、中身が空でない場合はエラーになります。

$ cat my-project/pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
]

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

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

プロジェクトのメタデータは、pyproject.tomlの[project]セクションに保存されます。 Poetry 2系では、PEP 621に準拠したこの形式が標準です。 authorsは、Gitの設定（user.name・user.email）から自動で入力されます。

既存ディレクトリに追加したい（`poetry init`）

$ cd my-project
$ poetry init

poetry initコマンドで、既存のディレクトリにpyproject.tomlを追加できます。プロンプトの表示にしたがって、プロジェクト情報（名前、説明、作成者、ライセンスなど）や依存パッケージを対話的に入力します。 poetry newと違って、README.mdやsrc/レイアウトは生成されません。

$ poetry init -n

-n（--no-interaction）オプションで、プロンプトを省略して最小限のpyproject.tomlのみ生成できます。あとから直接編集できるので、間違えても大丈夫です。

依存パッケージを追加・削除したい（`poetry add` / `poetry remove`）

$ poetry add requests
Using version ^2.34.2 for requests

Updating dependencies
Resolving dependencies...

Package operations: 5 installs, 0 updates, 0 removals

  - Installing certifi (2026.7.22)
  - Installing charset-normalizer (3.5.1)
  - Installing idna (3.19)
  - Installing urllib3 (2.7.0)
  - Installing requests (2.34.2)

Writing lock file

$ poetry remove requests
Updating dependencies
Resolving dependencies...

Package operations: 0 installs, 0 updates, 5 removals

  - Removing certifi (2026.7.22)
  - Removing charset-normalizer (3.5.1)
  - Removing idna (3.19)
  - Removing requests (2.34.2)
  - Removing urllib3 (2.7.0)

Writing lock file

poetry addで依存パッケージを追加、poetry removeで依存パッケージを削除できます。

pyproject.tomlの[project]セクションにあるdependenciesにパッケージ情報が記録され、 poetry.lockファイルも自動で更新されます。バージョンを指定しない場合は、^2.34.2のようにキャレット記法（メジャーバージョン内での自動更新を許可）で記録されます。

$ poetry add --dry-run httpx

--dry-runオプションで、実際にインストールせず、追加・更新されるパッケージを事前に確認できます。

開発依存パッケージを追加したい（`--group`）

$ poetry add --group dev pytest
$ poetry add --group dev ruff
$ poetry add --group dev pre-commit

--groupオプションで、依存パッケージをグループ化できます。 pyproject.tomlの[dependency-groups]セクションに、グループごとに記録されます。

開発のみに必要なツールは--group devでまとめておくと便利です。古い--dev（短縮形-D）オプションは、現在も-G devのショートカットとして使えますが、複数のグループを使い分けたい場合は--groupを使うのが分かりやすいです。

オプション依存パッケージを追加したい（`--optional`）

$ poetry add --optional viz matplotlib

--optional <extra名>オプションで、パッケージのオプション機能として依存を追加できます。 pyproject.tomlの[project.optional-dependencies]セクションに、指定したextra名で追加されます。利用者はpip install my-project[viz]のように、extra名を指定してインストールできます。

注釈

--groupと--optionalは似ていますが、目的が異なります。 --group（[dependency-groups]）は開発・CI用の内部的な依存分類で、パッケージには含まれません。 --optional（[project.optional-dependencies]）は、利用者が選択してインストールできる公開機能で、パッケージのextrasとして配布されます。

パッケージをインストール・同期したい（`poetry install` / `poetry sync`）

$ poetry install
Installing dependencies from lock file

No dependencies to install or update

Installing the current project: my-project (0.1.0)

poetry installコマンドで、poetry.lockに記録されたパッケージをインストールできます。 poetry.lockがない場合は、pyproject.tomlから自動で生成されます。初回実行時は、仮想環境も自動で作成されます。

$ poetry sync
Installing dependencies from lock file

Package operations: 0 installs, 0 updates, 3 removals

  - Removing markdown-it-py (4.2.0)
  - Removing mdurl (0.1.2)
  - Removing rich (15.0.0)

Installing the current project: my-project (0.1.0)

poetry syncは、仮想環境をpoetry.lockの内容に完全一致させるコマンドです。ロックファイルにないパッケージは、アンインストールされます。

注釈

poetry installは追加・更新のみ行い、環境に残っている余分なパッケージは削除しません。 poetry sync（poetry install --syncと同等ですが、--syncオプションは非推奨）は、ロックファイルの内容と環境を完全に一致させ、余分なパッケージも削除します。

たとえばpoetry run pip install richのようにロックファイル管理外でパッケージを追加した場合、 poetry installではrichは残ったままですが、poetry syncを実行すると削除されます。

$ poetry install --no-root
$ poetry install --all-groups
$ poetry install --all-extras

--no-rootオプションで、プロジェクト自身（ルートパッケージ）のインストールを除外できます。 --all-groupsオプションで、[dependency-groups]のすべてのグループを、 --all-extrasオプションで、[project.optional-dependencies]のすべてのextraをインストール対象にできます。どちらも指定しない場合、デフォルトの対象はmainグループの依存のみです。

パッケージを実行したい（`poetry run`）

$ poetry run python main.py
Hello, World!

$ poetry run pytest
===== test session starts =====
tests/test_main.py .                                       [100%]
1 passed

poetry runコマンドで、プロジェクトの仮想環境を使って外部コマンドやスクリプトを実行できます。仮想環境の手動アクティベーションは不要です。

仮想環境したい（`poetry env`）

$ poetry env info
Virtualenv
Python:         3.12.7
Implementation: CPython
Path:           ~/.cache/pypoetry/virtualenvs/my-project-3zgY0R6r-py3.12
Executable:     ~/.cache/pypoetry/virtualenvs/my-project-3zgY0R6r-py3.12/bin/python
Valid:          True

poetry env infoコマンドで、現在のプロジェクトに紐づく仮想環境の情報を確認できます。 poetry installやpoetry addをはじめて実行したときに、仮想環境が自動で作成されます。

$ poetry env list
my-project-3zgY0R6r-py3.12 (Activated)

poetry env listコマンドで、プロジェクトに紐づく仮想環境の一覧を確認できます。

$ poetry env activate
. ~/.cache/pypoetry/virtualenvs/my-project-3zgY0R6r-py3.12/bin/activate

poetry env activateコマンドは、仮想環境を有効化するコマンド文字列を出力します。コマンドを直接実行するわけではないので、evalと組み合わせて使います。

$ eval $(poetry env activate)
(my-project-py3.12) $ deactivate

注意

Poetry 2.0以降、対話的にシェルへ入るpoetry shellコマンドは標準では使えなくなりました。かわりにpoetry env activate（推奨）か、shellプラグインを別途インストールして使う必要があります。 poetry env activateはpoetry shellの完全な代替ではない点に注意してください（サブシェルを起動せず、コマンド文字列を出力するだけです）。

$ poetry env use 3.11
$ poetry env use python3.12

poetry env useコマンドで、プロジェクトに使用するPythonバージョンを指定して、仮想環境を作り直せます。

$ poetry env remove test-my-project
$ poetry env remove --all

poetry env removeコマンドで、仮想環境を削除できます。 --allオプションで、プロジェクトに紐づくすべての仮想環境を削除できます。

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

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

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

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

注意

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

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

$ poetry config virtualenvs.options.system-site-packages true

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

PyROOTのように、通常のpip installでは入手できず、システムのパッケージマネージャー経由でしかインストールできないパッケージを、仮想環境からそのまま利用したい場合に有効です。

コード品質をチェックしたい（`poetry check`）

$ poetry check
All set!

poetry checkコマンドで、pyproject.tomlの内容が正しいか、poetry.lockと整合しているかを確認できます。

$ poetry check --lock

--lockオプションで、現在のpyproject.tomlに対応するpoetry.lockが存在するかを確認できます。 CIでロックファイルの更新忘れを検知するのに向いています。

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

$ poetry build
Building my-project (0.1.0)
Building sdist
  - Building sdist
  - Built my_project-0.1.0.tar.gz
Building wheel
  - Building wheel
  - Built my_project-0.1.0-py3-none-any.whl

poetry buildコマンドでパッケージをビルドできます。ビルドすると、dist/ディレクトリの中に、 wheel形式（.whl）とsdist形式（.tar.gz）のファイルが生成されます。

$ poetry build --format wheel
$ poetry build --format sdist

--format（短縮形-f）オプションで、どちらか片方の形式だけをビルドできます。

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

// 実際にはアップロードせず、動作を確認する
$ poetry publish --dry-run

$ poetry publish
Publishing my-project (0.1.0) to PyPI
 - Uploading my_project-0.1.0-py3-none-any.whl
 - Uploading my_project-0.1.0.tar.gz

poetry publishで、PyPIにパッケージを公開できます。 --dry-runオプションで、実際にアップロードせずに、公開の流れ（認証やファイルチェック）だけを確認できます。はじめて公開する前の動作確認に便利です。

--buildオプションを付けると、poetry buildを省略して、公開前に自動でビルドできます。

参考

詳しい公開手順については、僕の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のみ設定が必要です。

// TestPyPIに公開
$ poetry publish -r testpypi --dry-run
$ poetry publish -r testpypi

-r（--repository）オプションで、公開先を切り替えられます。はじめて公開するパッケージは、まずTestPyPIに公開して動作テストしてからPyPIに本番公開することをオススメします。

注釈

PyPIとTestPyPIは、サービスとしては別物です。それぞれのサービスでアカウントを作成してください。また、プロジェクトごとにAPIトークンを発行してください。

注意

PyPIとTestPyPIには、同じ名前のパッケージは登録できません。プロジェクトを作成する段階で、パッケージ名の重複がないか確認してください。また、同じバージョンの再アップロード（上書き）もできません。変更内容に応じてバージョンを更新してください。

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

設定を管理したい（`poetry config`）

$ poetry config --list
cache-dir = "~/.cache/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

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

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

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

まっさらから作りたい（poetry new）

既存ディレクトリに追加したい（poetry init）

依存パッケージを追加・削除したい（poetry add / poetry remove）

開発依存パッケージを追加したい（--group）

オプション依存パッケージを追加したい（--optional）

パッケージをインストール・同期したい（poetry install / poetry sync）

パッケージを実行したい（poetry run）

仮想環境したい（poetry env）