簡介

簡介 #

Poetry 是 Python 中用來進行相依關係管理及封裝的工具。它允許你宣告專案所依賴的函式庫，它會為你管理（安裝/更新）這些函式庫。Poetry 會提供鎖定檔（lock file）以確保安裝時的可重複性，它也能夠建置你的專案以便進行發行。

系統需求 #

Poetry 要求執行 Python 3.8 以上版本。它支援多平台，且目標是讓它在 Linux、macOS 與 Windows 上都能正常運作。

安裝 #

警告

Poetry 應該隨時安裝在專屬的虛擬環境中，以將它與系統其他部分隔離。絕不應安裝在要由 Poetry 管理的專案環境中。這可確保 Poetry 自身的相依關係不會意外升級或解除安裝。（以下每種安裝方式都會確保 Poetry 安裝在隔離的環境中。）此外，安裝 Poetry 的隔離虛擬環境不應啟用以執行 Poetry 命令。

注意事項

如果你檢視的是開發分支的說明文件，你可能希望安裝 Poetry 的預覽版或開發版。請參閱進階的安裝說明，以使用 Poetry 的預覽版或其他版本。

pipx 用於全局安裝 Python CLI 應用程式，同時仍將其隔離在虛擬環境中。當用於安裝 Poetry 時，pipx 將管理升級和解除安裝。

安裝 pipx

如果尚未安裝 pipx，您可以在官方 pipx 安裝說明中依照任一選項進行操作。任何非遠古版本的 pipx 都能使用。
安裝 Poetry
```
pipx install poetry
```
手動安裝 Poetry

注意事項

如果您只想取得最新版本，並且已按照前一步驟安裝 Poetry，您可以跳過此步驟。此步驟詳細說明此安裝方法的進階用法。例如，從來源安裝 Poetry、同時安裝多個版本等等。

pipx 可以安裝不同版本的 Poetry，語法與 pip 相同
```
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 2，而不是 Python 3。我們總是建議使用 python3 二進位檔案，以避免造成歧義。

Windows (Powershell)
```
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
```
注意事項

如果你透過 Microsoft 商店安裝 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 wrapper
- 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 (版本 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。

詩可以使用 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

詩會在 $VENV_PATH/bin/poetry 中，並且可以直接呼叫或連結至其他地方。

若要解除安裝 Poetry，請直接移除 $VENV_PATH 目錄。

不同於開發環境（希望使用最新工具），在 CI 環境中應優先考慮可重現性。以下有一些在這種環境中安裝 Poetry 的建議。

版本固定

無論使用哪一種方式，強烈建議明確控制所使用的 Poetry 版本，這樣才能在執行驗證後進行升級。每種安裝方式的語法都不同，可以用在下列範例中設定版本。

使用 pipx

如同 pipx 是在開發使用時強大的工具，它在 CI 環境中也是同樣地有用，應該是你在 CI 中使用 Poetry 的首選之一。

pipx install poetry==1.2.0

使用 install.python-poetry.org

注意事項

官方安裝指令碼 (install.python-poetry.org) 提供 Poetry 的精簡而簡易安裝，足夠讓開發人員使用或用於簡單管線。然而，在 CI 環境中應認真考慮其他兩個支援的安裝方式（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

之後您必須將 poetry 新增至 ~/.zshrc中您的外掛程式陣列中

plugins(
	poetry
	...
	)

prezto #

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

注意事項

您可能需要重新啟動終端機才能套用這些變更。