Introduction

PoetryはPythonの依存関係管理とパッケージングのためのツールです。プロジェクトが依存するライブラリを宣言し、管理(インストール/更新)することができます。 Poetryは、繰り返し可能なインストールを保証するためのロックファイルを提供し、配布用のプロジェクトを構築することができます。

System requirements

Poetryには Python 3.8+ が必要です。これはマルチプラットフォームであり、目標はLinux、macOS、Windowsで同等に動作するようにすることです。

Installation

Warning

Poetryは、システムの他の部分から分離するために、常に専用の仮想環境にインストールする必要があります。 Poetryによって管理されるプロジェクトの環境にインストールすることはできません。これにより、Poetry自体の依存関係が誤ってアップグレードされたりアンインストールされたりすることがなくなります。 (次の各インストール方法では、Poetryが独立した環境にインストールされます)。さらに、Poetryがインストールされている隔離された仮想環境は、Poetryコマンドを実行するために起動されるべきではありません。

Note

開発ブランチのドキュメントを表示している場合は、Poetryのプレビュー版または開発版をインストールできます。 Poetryのプレビューまたは代替バージョンを使用するには、advancedのインストール手順を参照してください。

installing-with-pipxinstalling-with-the-official-installerinstalling-manuallyci-recommendations

pipxは、Python CLIアプリケーションを仮想環境に隔離しながら、グローバルにインストールするために使用されます。 pipxは、Poetryのインストールに使用された場合、アップグレードとアンインストールを管理します。

Install pipx

pipxがまだインストールされていない場合は、official pipx installation instructionsに記載されている任意のオプションに従ってください。 pipxの古いバージョンでなければ、どんなものでもかまいません。

Install Poetry

pipx install poetry

Install Poetry (advanced)

Note

前の手順で説明したように、単に最新バージョンとすでにインストールされているPoetryが必要な場合は、この手順をスキップできます。この手順では、このインストール方法の高度な使用方法について詳しく説明します。たとえば、ソースからPoetryをインストールしたり、複数のバージョンを同時にインストールしたりします。

pipと同様、pipx は異なるバージョンのPoetryをインストールすることができます。

pipx install poetry==1.2.0

pipxはPoetryのバージョンを並行してインストールすることもできるので、代替バージョンやプレリリースバージョンを簡単にテストすることができます。各バージョンには、ユーザーが指定した一意の接尾辞が与えられ、一意のバイナリ名を作成するために使用されます。

pipx install --suffix=@1.2.0 poetry==1.2.0
poetry@1.2.0 --version

pipx install --suffix=@preview --pip-args=--pre poetry
poetry@preview --version

最後に、pipxは有効なpip requirement specをインストールできます。これにより、gitからの開発バージョンのインストールや、プルリクエストのローカルテストが可能になります。

pipx install --suffix @main git+https://github.com/python-poetry/poetry.git@main
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head

Update Poetry

pipx upgrade poetry

Uninstall Poetry

pipx uninstall poetry

Poetryを新しい仮想環境にインストールし、Poetryが独自の環境を管理できるようにするカスタムインストーラを提供します。

Install Poetry

インストーラスクリプトは、install.python-poetry.orgから直接入手でき、its own repositoryで開発されています。スクリプトは、直接実行することも("curl python"など)、ダウンロードしてディスクから実行することもできます(CI環境など)。

Warning

install-poetry.pyインストーラは廃止され、Poetryリポジトリから削除されました。ツリー内のバージョンから上記のスタンドアロンバージョンに移行してください。

Linux, macOS, Windows (WSL)

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

Note

注意:一部のシステムでは、pythonがpython3ではなくPython 2を参照している場合があります。あいまいさを避けるために、常にpython3バイナリをお勧めします。

Windows (Powershell)

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Note

Microsoft StoreからPythonをインストールした場合は、上記のコマンドのpyをpythonに置き換えてください。

Install Poetry (advanced)

Note

前の手順で説明したように、単に最新バージョンとすでにインストールされているPoetryが必要な場合は、この手順をスキップできます。この手順では、このインストール方法の高度な使用方法について詳しく説明します。たとえば、ソースからのPoetryのインストール、プレリリースビルドの使用、別のインストール場所の設定などです。

デフォルトでは、Poetryはプラットフォームおよびユーザー固有のディレクトリにインストールされます。

macOSでは~/Library/Application Support/pypoetryです。
Linux/Unixでは~/.local/share/pypoetryです。
Windowsの場合は%APPDATA%\pypoetryです。

これを変更したい場合は、$POETRY_HOME環境変数を定義します。

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

プレリリース版をインストールしたい場合は、インストールスクリプトに--previewオプションを渡すか、または$POETRY_PREVIEW環境変数を使用します。

curl -sSL https://install.python-poetry.org | python3 - --preview
curl -sSL https://install.python-poetry.org | POETRY_PREVIEW=1 python3 -

同様に、特定のバージョンをインストールしたい場合は、--versionオプションまたは$POETRY_VERSION環境変数を使用できます。

curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -

--gitオプションを使用して、gitリポジトリからPoetryをインストールすることもできます。

curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@main

異なるバージョンのPoetryを並行してインストールする場合は、pipxとサフィックスを指定してインストールすることをお勧めします。

Add Poetry to your PATH

インストーラは、よく知られたプラットフォーム固有のディレクトリにpoetryラッパーを作成します。

Unixでは$HOME/.local/binです。
Windowsでは、%APPDATA%\Python\Scriptsです。
もし$POETRY_HOMEが設定されていれば$POETRY_HOME/binです。

このディレクトリが$PATHに存在しない場合は、Poetryをpoetryとして呼び出すために追加することができます。

あるいは、poetryバイナリへのフルパスを常に使用することもできます。

macOSでは~/Library/Application Support/pypoetry/venv/bin/poetryです。
Linux/Unixでは~/.local/share/pypoetry/venv/bin/poetryです。
Windowsでは、%APPDATA%\pypoetry\venv\Scripts\poetryです。
もし$POETRY_HOMEが設定されていれば$POETRY_HOME/venv/bin/poetryです。

Use Poetry

Poetryがインストールされて$PATHに入ると、以下を実行できます。

poetry --version

Poetry(version 1.2.0)のようなものが表示されたら、インストールは使用可能です。

Update Poetry

Poetryは、公式インストーラを使用してインストールすると、自動的に更新されます。

Warning

特にWindowsでは、self updateが問題になる可能性があるため、インストーラを使用して再インストールすることをお勧めします。

poetry self update

プレリリース版をインストールしたい場合は、--previewオプションを使用できます。

poetry self update --preview

そして最後に、特定のバージョンをインストールしたい場合は、それを引数としてself updateに渡すことができます。

poetry self update 1.2.0

Warning

Poetry1.1シリーズのリリースを1.2以降のシリーズのリリースにインプレイス更新することはできません。新しいリリースに移行するには、元のインストール方法を使用してアンインストールしてから、methods aboveを使用して再インストールします。

Uninstall Poetry

Poetryがあなたの好みではないと判断した場合は、--uninstallオプションを指定してインストーラを再度実行するか、インストーラを実行する前にPOETRY_UNINSTALL環境変数を設定することで、システムから完全に削除できます。

curl -sSL https://install.python-poetry.org | python3 - --uninstall
curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -

Warning

非推奨のget-poetry.pyスクリプトを使用してインストールした場合は、それが使用するパスを手動で削除する必要があります。

rm -rf "${POETRY_HOME:-~/.poetry}"

また、シェル設定の$PATHから~/.poetry/binがあれば削除してください。

Poetryはpipとvenvモジュールを使って手動でインストールできます。そうすることで、基本的に公式インストーラによって実行されるステップを実行します。これは高度なインストール方法であるため、この手順はUnix専用であり、gitからのインストールなどの特定の例は省略されています。

変数$VENV_PATHは、仮想環境が作成されたパスを示すために使用されます。

python3 -m venv $VENV_PATH
$VENV_PATH/bin/pip install -U pip setuptools
$VENV_PATH/bin/pip install poetry

Poetryは$VENV_PATH/bin/poetryにあり、直接呼び出すことも、別の場所にシンボリックリンクすることもできます。

Poetryをアンインストールするには、$VENV_PATHディレクトリ全体を削除するだけです。

最新のツールを使用することが望ましい開発環境とは異なり、CI環境では再現性を優先する必要があります。このような環境にPoetryをインストールするためのヒントをいくつか紹介します。

Version pinning

どのような方法を使用する場合でも、使用するPoetryのバージョンを明示的に制御して、独自の検証を実行した後にアップグレードできるようにすることを強くお勧めします。次の例で使用するバージョンを設定する構文は、インストール方法ごとに異なります。

Using pipx

pipxが開発用の強力なツールであるのと同じように、CI環境でも同様に有用であり、CIでPoetryを使用するためのよい選択肢の1つにすべきです。

pipx install poetry==1.2.0

Using install.python-poetry.org

Note

公式インストーラスクリプト(install.python-poetry.org)は、開発者の使用や単純なパイプラインに十分な、合理化され簡素化されたPoetryのインストールを提供します。ただし、CI環境では、サポートされている他の2つのインストール方法(pipxとmanual)を真剣に検討する必要があります。

パイプラインの安定性を確保し、実行されるコードの制御を維持するために、CIパイプラインからアクセス可能な場所にインストーラスクリプトのコピーをダウンロードする(またはリポジトリのコピーを維持する)ことを強くお勧めします。

デフォルトでは、インストーラはユーザ固有のディレクトリにインストールします。より複雑なパイプラインでは、Poetryへのアクセスが困難になる可能性がある(特にマルチステージコンテナビルドのような場合)。 CIで公式インストーラを使用する場合は、正確なパスを制御できるように、$POETRY_HOMEを使用することを強くお勧めします。

export POETRY_HOME=/opt/poetry
python3 install-poetry.py --version 1.2.0
$POETRY_HOME/bin/poetry --version

Using pip (aka manually)

CI環境で最大限の制御を行うには、pipを使用したインストールが完全にサポートされており、考慮する必要があります。これには、より明示的なコマンドとPythonパッケージングの知識が必要ですが、その代わりに最高のデバッグエクスペリエンスが提供され、外部ツールの使用が最小限に抑えられます。

export POETRY_HOME=/opt/poetry
python3 -m venv $POETRY_HOME
$POETRY_HOME/bin/pip install poetry==1.2.0
$POETRY_HOME/bin/poetry --version

Note

pipを使用してPoetryをインストールする場合は、Poetryによって管理されるターゲット環境と同じではない**分離された環境にPoetryをインストールしてください。 Poetryとプロジェクトが同じ環境にインストールされている場合、Poetry自体の依存関係がアップグレードまたはアンインストールされる可能性があります(デバッグや理解が困難なエラーが発生します)。

Enable tab completion for Bash, Fish, or Zsh

poetryはBash、Fish、Zsh用の補完スクリプトの生成をサポートしています。詳細についてはpoetry help completionsを参照してください。

Bash

Auto-loaded (recommended)

poetry completions bash >> ~/.bash_completion

Lazy-loaded

poetry completions bash > ${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/poetry

Fish

poetry completions fish > ~/.config/fish/completions/poetry.fish

Zsh

poetry completions zsh > ~/.zfunc/_poetry

次の行が存在しない場合は、~/.zshrcに追加する必要があります。

fpath+=~/.zfunc
autoload -Uz compinit && compinit

Oh My Zsh

mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry

次に、~/.zshrcのプラグイン配列にpoetryを追加する必要があります。

plugins(
    poetry
    ...
    )

prezto

poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry

Note

この変更を有効にするには、シェルの再起動が必要な場合があります。