Skip to content

コマンド🔗

これまでに、何かをするためのコマンドラインインターフェースの使い方を学びました。 この章では、全ての利用可能なコマンドについて記述します。

コマントラインでヘルプを出すには、 poetry と呼び出すとコマンドの完全なリストが見られて、コマンドのどれかに --help を付けて実行するとより詳しい情報が得られます。

グローバルオプション🔗

  • --verbose (-v|vv|vvv): メッセージの冗長さを増やします: 1つでは標準の出力、2つではより冗長な出力、3つではデバッグ出力です。
  • --help (-h) : ヘルプ情報を表示します。
  • --quiet (-q) : メッセージを出力しません。
  • --ansi: ANSI出力を強制します。
  • --no-ansi: ANSI出力を無効にします。
  • --version (-V): このアプリケーションのバージョンを表示します。

new🔗

このコマンドは、ほとんどのプロジェクトに適するディレクトリ構造を作成して、新しいPythonプロジェクトに勢いをつける助けをしてくれます。

poetry new my-package

というコマンドは次のフォルダを作成します:

my-package
├── pyproject.toml
├── README.rst
├── my_package
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_my_package.py

フォルダとは別のプロジェクト名を付けたい場合は、 --name オプションで渡せます:

poetry new my-folder --name my-package

srcフォルダを使いたい場合は、 --src オプションが使えます:

poetry new --src my-package

このコマンドは次のようなフォルダ構成を作成します:

my-package
├── pyproject.toml
├── README.rst
├── src
│   └── my_package
│       └── __init__.py
└── tests
    ├── __init__.py
    └── test_my_package.py

init🔗

このコマンドは、パッケージについての基本的な情報を提供するよう促して、 pyproject.toml ファイルを対話的に作成する助けになります。

このコマンドは、賢いデフォルト設定を使いつつ、フィールドを埋めるよう対話的に求めます。

poetry init

Options🔗

  • --name: パッケージ名。
  • --description: パッケージの説明。
  • --author: パッケージの作者。
  • --python 互換性のあるPythonバージョン。
  • --dependency: バージョン制約付きの要求されるパッケージ。 foo:1.0.0 形式でなければいけません。
  • --dev-dependency: 開発時に要求されるパッケージ、 --require を参照してください。

install🔗

install コマンドは、現在のプロジェクトにある pyproject.toml ファイルを読み込み、依存関係を解決し、インストールします。

poetry install

poetry.lock ファイルが今のディレクトリにある場合は、依存関係を解決する代わりに、ロックファイルにある厳密なバージョンを使います。 これにより、そのライブラリを使う全員が同じバージョンの依存関係を手に入れることを保証します。

poetry.lock ファイルが無い場合は、Poetryは依存関係解決の結果に従ってロックファイルを作成します。

--no-dev オプションを渡すことで、開発用の依存関係をインストールさせないで欲しいことをコマンドに指定できます。

poetry install --no-dev

既にlockファイルに存在しない古い依存関係を取り除きたい場合は、--remove-untracked オプションを使用してください。

poetry install --remove-untracked

-E|--extras オプションを渡すことで、インストールして欲しい追加の依存関係の指定もできます (より詳しいことは Extras を参照してください)

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql

デフォルトでは、poetry は install を実行するたびにプロジェクトのパッケージをインストールします:

$ poetry install
Installing dependencies from lock file

No dependencies to install or update

  - Installing <your-package-name> (x.x.x)

このインストールをスキップしたい場合は、--no-root オプションを使ってください。

poetry install --no-root

Options🔗

  • --no-dev: 開発用の依存関係をインストールしない。
  • --no-root: ルートパッケージ (あなたのプロジェクト) をインストールしない。
  • --extras (-E): インストールする機能 (複数値も可能です)。

update🔗

最新バージョンの依存関係を取得し、 poetry.lock を更新するには、 update コマンドを使いましょう。

poetry update

このコマンドは、プロジェクトの全ての依存関係を解決し、その厳密なバージョンを poetry.lock に書き込みます。

全てではない一部のパッケージだけを更新したい場合は、このように並べて指定できます:

poetry update requests toml

これは、pyproject.toml ファイルに指定されているバージョン制約を越えた依存関係のバージョンへの更新はしないことに気を付けてください。別の言い方をすれば、foo のバージョン制約指定が ~2.3 あるいは 2.3 で、2.4 が利用可能な場合では、poetry update foo は何もしないということです。foo の更新をするには、例えば ^2.3 へ制約を更新しなければいけません。制約の更新は add コマンドでできます。

Options🔗

  • --dry-run : 作業を表示しますが、何も実行しません (暗黙的に --verbose が有効になります)。
  • --no-dev : 開発用の依存関係をインストールしません。
  • --lock : インストールを行いません (ロックファイルを更新するだけです)。

add🔗

add コマンドは pyproject.toml に要求しているパッケージを追加し、インストールします。

バージョン制約を指定いない場合、poetryは利用可能なパッケージバージョンに基づいて適したものを選びます。

poetry add requests pendulum

パッケージを追加するときに、次のように制約を指定できます:

poetry add pendulum@^2.0.5
poetry add "pendulum>=2.0.5"

既に追加してあるパッケージを追加しようとすると、エラーが出ます。 ただし、上にあるような制約を指定している場合は、その指定された制約を使って依存関係が更新されます。既に追加してある依存関係の最新バージョンが欲しい場合は、 latest という特殊な制約が使えます:

poetry add pendulum@latest

git 依存関係の追加もできます:

poetry add git+https://github.com/sdispater/pendulum.git

あるいは、httpsの代わりにsshを使い:

poetry add git+ssh://git@github.com/sdispater/pendulum.git

特定のブランチ、タグ、リビジョンをチェックアウトする必要がある場合に、 add を使っているときはその指定ができます:

poetry add git+https://github.com/sdispater/pendulum.git#develop
poetry add git+https://github.com/sdispater/pendulum.git#2.0.5

のようにするか、ローカルのディレクトリやファイルを指し示すようにします:

poetry add ./my-package/
poetry add ../my-package/dist/my-package-0.1.0.tar.gz
poetry add ../my-package/dist/my_package-0.1.0.whl

依存パッケージを編集可能モードでインストールしたい場合は、pyproject.toml ファイルに指定できます。これはつまり、手元のディレクトリの変更が直接環境に反映されるということです。

[tool.poetry.dependencies]
my-package = {path = "../my/path", develop = true}

注意

poetry 1.1 以前のpath依存関係はデフォルトで編集可能モードでインストールされます。全てのpoetryバージョンと振る舞いを揃えるには、 毎回 develop 属性を明示的に設定する必要があります。

インストールしたいパッケージがextraを提供している場合、パッケージを追加するときにそのextrasを指定できます:

poetry add requests[security,socks]
poetry add "requests[security,socks]~=2.22.0"
poetry add "git+https://github.com/pallets/flask.git@1.1.1[dotenv,dev]"

Options🔗

  • --dev (-D): 開発用の依存関係としてパッケージを追加します。
  • --path: 依存関係へのパス。
  • --optional : オプションの依存関係を追加します。
  • --dry-run : 作業を表示しますが、何も実行しません (暗黙的に --verbose が有効になります)。
  • --lock : インストールを行いません (ロックファイルを更新するだけです)。

remove🔗

remove コマンドは、現在のインストールされたパッケージの一覧からパッケージを削除します。

poetry remove pendulum

Options🔗

  • --dev (-D): 開発用の依存関係からパッケージを削除します。
  • --dry-run : 作業を表示しますが、何も実行しません (暗黙的に --verbose が有効になります)。

show🔗

全ての利用可能なパッケージを列挙するには、 show コマンドが使えます。

poetry show

ある特定のパッケージの詳細を見たい場合は、パッケージ名を渡せます。

poetry show pendulum

name        : pendulum
version     : 1.4.2
description : Python datetimes made easy

dependencies:
 - python-dateutil >=2.6.1
 - tzlocal >=1.4
 - pytzdata >=2017.2.2

Options🔗

  • --no-dev: 開発用の依存関係を列挙しません。
  • --tree: 依存関係を木構造で列挙します。
  • --latest (-l): 最新バージョンを表示します。
  • --outdated (-o): 古くなったパッケージの最新バージョンだけを表示します。

build🔗

build コマンドは、ソースアーカイブとwheelアーカイブへビルドします。

poetry build

現時点では、ピュアPythonのwheelのみサポートされていることに注意してください。

Options🔗

  • --format (-f): 形式をwheelもしくはsdistに限定します。

publish🔗

このコマンドは、前に build コマンドでビルドしたパッケージを、リモートレポジトリに公開します。

初めて提出する場合には、このコマンドは、アップロードの前に自動的にパッケージの登録を行います。

poetry publish

--build オプションを渡すと、パッケージのビルドもしてくれます。

Options🔗

  • --repository (-r): パッケージを登録するレポジトリ (デフォルト: pypi) です。 config コマンドで設定したレポジトリ名と一致しなければなりません。
  • --username (-u): レポジトリにアクセスするためのユーザー名。
  • --password (-p): レポジトリにアクセスするためのパスワード。
  • --dry-run: パッケージのアップロードを除いた全ての動作を実行します。

config🔗

config コマンドを使うと、Poetryのsettingsやrepositoriesの設定を編集できます。

poetry config --list

使い方🔗

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

setting-key は設定のオプション名で setting-value1 は設定値です。 利用可能な全ての設定は 設定 を参照してください。

Options🔗

  • --unset: setting-key で名付けられた設定要素を削除します。
  • --list: 現在の設定変数の一覧を表示します。

run🔗

run コマンドは、与えられたコマンドをプロジェクトの仮想環境の中で実行します。

poetry run python -V

このコマンドは pyproject.toml に定義されたスクリプトうち1つを実行することもできます。

それなので、次のように定義されたスクリプトがある場合:

[tool.poetry.scripts]
my-script = "my_module:main"

このようにして実行できます:

poetry run my-script

このコマンドにはオプションが無いことに注意してください。

shell🔗

shell コマンドは、 $SHELL 環境変数に従って、仮想環境の中でシェルを起動します。 仮想環境がまだ無い場合は、作成されます。

poetry shell

check🔗

check コマンドは、 pyproject.toml ファイルの構造を検証し、エラーがあった場合は、詳細なレポートを返します。

poetry check

このコマンドは、リモートの目録にあるパッケージを検索します。

poetry search requests pendulum

lock🔗

このコマンドは、(インストールはせずに) pyproject.toml に指定されている依存関係をロックします。

注意

By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the --no-update option.

poetry lock

Options🔗

  • --no-update: Do not update locked versions, only refresh lock file.

version🔗

このコマンドは現在のプロジェクトのバージョンを表示したり、正しいバージョン更新規則を指定された場合、プロジェクトのバージョンを進めて pyproject.toml へ新しいバージョンを書き戻します。

新しいバージョンは理想的には、有効な セマンティックバージョニング 文字列か、有効な更新規則であるべきです。有効な更新規則: patch, minor, major, prepatch, preminor, premajor, prerelease 。

下にある表は、これらの規則で発生する効果を具体例で説明しているものです。

rule before after
major 1.3.0 2.0.0
minor 2.1.4 2.2.0
patch 4.1.1 4.1.2
premajor 1.0.2 2.0.0-alpha.0
preminor 1.0.2 1.1.0-alpha.0
prepatch 1.0.2 1.0.3-alpha.0
prerelease 1.0.2 1.0.3-alpha.0
prerelease 1.0.3-alpha.0 1.0.3-alpha.1
prerelease 1.0.3-beta.0 1.0.3-beta.1

Options🔗

  • --short (-s): バージョンナンバーだけを出力します。

export🔗

このコマンドはlockファイルを他のフォーマットへ出力します。

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

注意

現時点では requirements.txt 形式のみをサポートしています。

Options🔗

  • --format (-f): 出力する形式（デフォルト: requirements.txt）。現時点では requirements.txt のみサポートされています。
  • --output (-o): 出力ファイル名。省略した場合は、標準出力に表示されます。
  • --dev: 開発用の依存関係を含めます。
  • --extras (-E): 含めたい依存関係のextra一式です。
  • --without-hashes: 出力したファイルのハッシュを除外します。
  • --with-credentials: extra目録の証明書を含めます。

env🔗

The env command regroups sub commands to interact with the virtualenvs associated with a specific project.

これらのコマンドについては 環境管理 を参照してください。

キャッシュ🔗

The cache command regroups sub commands to interact with Poetry's cache.

キャッシュリスト🔗

cache list コマンドはPoetryの利用可能なキャッシュの一覧を出力します。

poetry cache list