はじめに

はじめに #

Poetryは、Pythonにおける**依存関係の管理**と**パッケージ化**のためのツールです。プロジェクトが依存するライブラリを宣言すると、Poetryがそれらのライブラリの管理（インストール/アップデート）を行います。Poetryは、再現可能なインストールを保証するためのロックファイルを提供し、配布用のプロジェクトをビルドできます。

システム要件 #

Poetryには、**Python 3.8以降**が必要です。マルチプラットフォームに対応しており、Linux、macOS、Windowsで同等の動作を目指しています。

インストール #

警告

Poetryは、システムの他の部分から分離するために、常に専用の仮想環境にインストールする必要があります。Poetryによって管理されるプロジェクトの環境にインストールしてはなりません。これにより、Poetry自身の依存関係が誤ってアップグレードまたはアンインストールされるのを防ぎます。（以下の各インストール方法は、Poetryが分離された環境にインストールされることを保証します。）さらに、poetryをインストールした分離された仮想環境は、poetryコマンドを実行するためにアクティブにしてはいけません。

注記

開発ブランチのドキュメントを参照している場合は、Poetryのプレビュー版または開発版をインストールすることをお勧めします。Poetryのプレビュー版または代替版を使用するには、**高度な**インストール手順を参照してください。

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

pipxのインストール

pipxがまだインストールされていない場合は、公式pipxインストール手順のいずれかのオプションに従うことができます。古いバージョンではないpipxであれば、どれでも動作します。
Poetryのインストール
```
pipx install poetry
```
Poetryのインストール（高度なユーザー向け）

注記

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

pipxは、pipと同じ構文を使用して、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要件指定をインストールできます。これにより、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
```
Poetryのアップデート
```
pipx upgrade poetry
```
Poetryのアンインストール
```
pipx uninstall poetry
```

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

Poetryのインストール

インストーラースクリプトは、install.python-poetry.orgで直接入手でき、独自のレポジトリで開発されています。スクリプトは直接実行できます（例：「curl python」）か、ダウンロードしてディスクから実行できます（例：CI環境）。

警告

install-poetry.pyインストーラは非推奨となり、Poetryリポジトリから削除されました。上記で説明されているスタンドアロンバージョンに移行してください。

Linux、macOS、Windows（WSL）
```
curl -sSL https://install.python-poetry.org | python3 -
```
注記

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

Windows（PowerShell）
```
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
```
注記

Microsoft StoreからPythonをインストールしている場合は、上記のコマンドでpyをpythonに置き換えてください。
Poetryのインストール（高度なユーザー向け）

注記

最新バージョンのみが必要で、前の手順で説明されているように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とサフィックスを使用したインストールが良い方法です。
Poetryを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。
Poetryを使用する

Poetry がインストールされ、$PATH に含まれている場合、以下を実行できます。
```
poetry --version
```
Poetry (version 1.2.0) のようなメッセージが表示されたら、インストールは完了です！
Poetryのアップデート

公式インストーラを使用してインストールされた Poetry は、自己更新機能を持っています。

警告

特に Windows では、self update が問題になる可能性があるため、インストーラによる再インストールが推奨されます。
```
poetry self update
```
プレリリース版をインストールしたい場合は、--preview オプションを使用できます。
```
poetry self update --preview
```
特定のバージョンをインストールしたい場合は、それを self update に引数として渡すことができます。
```
poetry self update 1.2.0
```
警告

Poetry 1.1 系リリースは、1.2 以降のリリースにインプレースで更新できません。新しいリリースに移行するには、元のインストール方法でアンインストールしてから、上記の方法を使用して再インストールしてください。
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 -
```
警告
非推奨の 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 環境では再現性を優先する必要があります。CI環境でのPoetryのインストールに関するいくつかの提案を以下に示します。

バージョン固定

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

pipx の使用

pipx は開発用途に強力なツールであると同時に、CI環境でも同様に役立ち、CIでのPoetryの使用において最上位の選択肢の1つとなるはずです。

pipx install poetry==1.2.0

install.python-poetry.org の使用

注記

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

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

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

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

pip の使用（手動インストール）

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

注記

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

Bash、Fish、または Zsh のタブ補完を有効にする #

poetry は、Bash、Fish、Zsh の補完スクリプトを生成できます。詳細は poetry help completions を参照してください。基本的には、次のいずれかを使用するだけです。

Bash #

自動読み込み（推奨） #

poetry completions bash >> ~/.bash_completion

遅延読み込み #

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 の plugins 配列に poetry を追加する必要があります。

plugins(
	poetry
	...
	)

prezto #

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

注記

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