組態

設定 #

透過 config 命令（在此處參閱更多使用方式）或直接從在您首次執行該命令時會自動建立的 config.toml 檔案可以設定 Poetry。此檔案通常可以在下列資料夾之一中找到

macOS：~/Library/Application Support/pypoetry
Windows：%APPDATA%\pypoetry

對於 Unix，我們遵循 XDG 規格並支援 $XDG_CONFIG_HOME。這表示預設為 ~/.config/pypoetry。

本機設定 #

Poetry 也提供能針對特定專案設定的功能，方法是將 --local 選項傳遞給 config 命令。

poetry config virtualenvs.create false --local

請注意

您在 Poetry 應用程式的本機設定會儲存在 poetry.toml 檔案中，此檔案與 pyproject.toml 不同。

警告

請小心將此檔案檢查進您的存放區，因為它可能含有使用者特定的資訊或敏感資訊。

列出目前設定 #

若要列出目前的設定，你可以使用 config 指令的 --list 選項

poetry config --list

它將會給你類似的結果

cache-dir = "/path/to/cache/directory"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = true
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /path/to/cache/directory/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

顯示單一的組態設定 #

如果你想看到特定設定的值，你可以將它的名稱提供給 config 指令

poetry config virtualenvs.path

若要取得支援設定的完整清單，請參閱可用設定。

加入或更新組態設定 #

若要變更或加入新的組態設定，你可以在設定的名稱後方傳遞一個值

poetry config virtualenvs.path /path/to/cache/directory/virtualenvs

若要取得支援設定的完整清單，請參閱可用設定。

移除特定設定 #

如果你想移除先前設定的設定，則可以使用 --unset 選項

poetry config virtualenvs.path --unset

設定會擷取它的預設值。

使用環境變數 #

有時候，特別是在結合使用 Poetry 與 CI 工具時，會比較容易使用環境變數，而不必執行組態指令。

Poetry 支援這一點，並且可以使用環境變數設定任何設定。

環境變數必須以 POETRY_ 作為開頭，並以設定的大寫名稱組成，將點號和破折號替換為底線， voici une 範例

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

這也適用於機密設定，例如憑證

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

預設目錄 #

Poetry 使用下列預設目錄

組態目錄 #

Linux：$XDG_CONFIG_HOME/pypoetry 或 ~/.config/pypoetry
Windows：%APPDATA%\pypoetry
MacOS：~/Library/Application Support/pypoetry

你可以透過設定 POETRY_CONFIG_DIR 環境變數來覆寫組態目錄。

資料目錄 #

Linux：$XDG_DATA_HOME/pypoetry 或 ~/.local/share/pypoetry
Windows：%APPDATA%\pypoetry
MacOS：~/Library/Application Support/pypoetry

你可以透過設定 POETRY_DATA_DIR 或 POETRY_HOME 環境變數來覆寫資料目錄。如果 POETRY_HOME 已設定，則會給予它較高的優先順序。

快取目錄 #

Linux：$XDG_CACHE_HOME/pypoetry 或 ~/.cache/pypoetry
Windows：%LOCALAPPDATA%\pypoetry
MacOS：~/Library/Caches/pypoetry

你可以透過設定 POETRY_CACHE_DIR 環境變數來覆寫快取目錄。

可用設定 #

`cache-dir` #

類型：文字

環境變數：POETRY_CACHE_DIR

Poetry 使用的快取目錄路徑。

預設是下列其中一個目錄

macOS：~/Library/Caches/pypoetry
Windows：C:\Users\<username>\AppData\Local\pypoetry\Cache
Unix：~/.cache/pypoetry

`experimental.system-git-client` #

類型: 布林值

預設值: false

環境變數: POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT

於 1.2.0 引入

對 git 相關工作使用系統 git 客戶端後端程式。

Poetry 預設對 git 相關工作使用 dulwich，以避免仰賴 git 客戶端。

如果您遇到任何問題，請設定為 true 以使用系統 git 後端程式。

`installer.max-workers` #

類型: 整數

預設值: 處理器核心數 + 4

環境變數: POETRY_INSTALLER_MAX_WORKERS

於 1.2.0 引入

設定並行安裝程式在使用中的最大工作執行緒數。處理器核心數由 os.cpu_count() 決定。如果這會引發 NotImplementedError 例外，處理器核心數假設為 1。

如果這個組態參數設定為大於 處理器核心數 + 4 的值，最大工作執行緒數仍然限制為 處理器核心數 + 4。

請注意

當 installer.parallel 設定為 false 時，這個組態會被忽略。

`installer.modern-installation` #

類型: 布林值

預設值: true

環境變數: POETRY_INSTALLER_MODERN_INSTALLATION

於 1.4.0 引入

對套件安裝使用較現代且快速的方法。

如果這會造成問題，您可以把它設定為 false 來停用，並在問題追蹤器回報您遇到的問題。

`installer.no-binary` #

類型: 字串 | 布林值

預設值: false

環境變數: POETRY_INSTALLER_NO_BINARY

於 1.2.0 引入

設定此組態時，使用者的套件發布格式政策可以針對全部套件或特定套件進行組態。

組態	說明
`:all:` 或 `true`	禁止所有套件的二進制發布。
`:none:` 或 `false`	允許所有套件的二進制發布。
`package[,package,..]`	僅禁止指定的套件的二進制發布。

請注意

如同這裡說明的所有組態，這是一項使用者特定組態。這表示在產生鎖定檔或解析相依關係時，不會考慮這項設定。這僅在選擇要安裝到 Poetry 管理環境的相依關係發行版時才會套用。

請注意

建議使用 --local 設定項目特定的用法。

poetry config --local installer.no-binary :all:

請注意

針對使用環境變數來設定的 CI 或容器環境，這可能很有用。

export POETRY_INSTALLER_NO_BINARY=:all:

警告

除非在系統範圍內需要此設定，否則在所有專案中進行全域設定時，如果設定不正確，可能會造成所有專案安裝時間變慢。

`installer.parallel` #

類型: 布林值

預設值: true

環境變數：POETRY_INSTALLER_PARALLEL

已於 1.1.4 中引入

使用新的安裝程式 (>=1.1.0) 時，使用並行執行。

`solver.lazy-wheel` #

類型: 布林值

預設值: true

環境變數：POETRY_SOLVER_LAZY_WHEEL

已於 1.8.0 中引入

不要下載整個輪件來提取元資料，而是使用 HTTP 範圍請求，以便僅下載輪件的 METADATA 檔案。特別是在網路連線速度慢時，此設定可以顯著加快依存關係解析速度。如果快取已填滿或伺服器不支援 HTTP 範圍請求，此設定不會有任何影響。

`virtualenvs.create` #

類型: 布林值

預設值: true

環境變數：POETRY_VIRTUALENVS_CREATE

如果還不存在，則建立新的虛擬環境。

如果設定為 false，Poetry 將不會建立新的虛擬環境。如果偵測到已啟用的虛擬環境或 {cache-dir}/virtualenvs 或 {project-dir}/.venv 中已有現有的虛擬環境，則 Poetry 會將依存關係安裝到這些虛擬環境中；否則，它會將依存關係安裝到系統 Python 環境中。

請注意

如果 Poetry 偵測到它在已啟用的虛擬環境中執行，它將永遠不會建立新的虛擬環境，無論 virtualenvs.create 設定為何值。

請注意

請注意，在系統環境中安裝依存關係可能會升級或解除安裝現有套件，從而導致其他應用程式中斷。在安裝專案後安裝其他 Python 套件可能會導致 Poetry 專案損毀。

這就是建議始終建立虛擬環境的原因。這在 Docker 容器中也適用，因為它們也可能包含其他 Python 套件。

`virtualenvs.in-project` #

類型: 布林值

預設：None

環境變數：POETRY_VIRTUALENVS_IN_PROJECT

在專案的根目錄中建立虛擬環境。

如果未明確設定，poetry 預設會在 {cache-dir}/virtualenvs 下建立虛擬環境，或者如果已經存在，則使用 {project-dir}/.venv 目錄。

如果設定為 true，則會在專案根目錄中名為 .venv 的資料夾中建立虛擬環境並預期會在這裡找到虛擬環境。

請注意

如果已經在 {cache-dir}/virtualenvs 中為專案建立虛擬環境，則將此變數設定為 true 也不會讓 poetry 建立或使用本機虛擬環境。

要讓此設定對已經處於該狀態的專案生效，必須刪除位於 {cache-dir}/virtualenvs 中的虛擬環境資料夾。

你可以使用指令 poetry env info --path 找出目前的專案中的虛擬環境（若有）儲存位置。

若設定為 false，poetry 將忽視任何現有的 .venv 目錄。

`virtualenvs.options.always-copy` #

類型: 布林值

預設值: false

環境變數：POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

於 1.2.0 引入

若設定為 true，--always-copy 參數將在建立虛擬環境時傳遞給 virtualenv，以便所有需要的檔案都會複製進去，而不是建立符號連結。

`virtualenvs.options.no-pip` #

類型: 布林值

預設值: false

環境變數：POETRY_VIRTUALENVS_OPTIONS_NO_PIP

於 1.2.0 引入

若設定為 true，--no-pip 參數將在建立虛擬環境時傳遞給 virtualenv。表示在建立新的虛擬環境時，不會在環境中安裝 pip。

請注意

Poetry 在其內部運作時，會使用 pip 輪子嵌入在 virtualenv 套件中，此套件已安裝為 Poetry 執行時間環境中的相依項。若使用者在這個選項設定為 true 時執行 poetry run pip，將使用 pip 的嵌入執行個體。

如果你想要一個沒有額外套件的虛擬環境，你可以安全地將此選項連同 no-setuptools 設定為 true。這適用於製作環境。

`virtualenvs.options.no-setuptools` #

類型: 布林值

預設值: false

環境變數：POETRY_VIRTUALENVS_OPTIONS_NO_SETUPTOOLS

於 1.2.0 引入

若設定為 true，--no-setuptools 參數將在建立虛擬環境時傳遞給 virtualenv。表示在建立新的虛擬環境時，不會在環境中安裝 setuptools。Poetry 在其內部運作中不需要 setuptools，而且可以安全地將此設定為 true。

對於使用 Python 3.12 或更新版本的環境，virtualenv 在建立虛擬環境時預設不安裝 setuptools。因此，在這些環境中，此 Poetry 組態選項沒有作用：無論如何都不會安裝 setuptools。如果你的專案依賴於 setuptools，你應該將其宣告為相依項。

警告

某些開發工具（例如 IDE）假設 setuptools（和其他）套件一定會存在並可以在虛擬環境中使用。這可能會導致這些工具中的一些功能無法如預期般運作。

`virtualenvs.options.system-site-packages` #

類型: 布林值

預設值: false

環境變數：POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

讓虛擬環境可以存取系統的 site-packages 目錄。套用於建立 virtualenv 時。

`virtualenvs.path` #

類型：文字

預設值：{cache-dir}/virtualenvs

環境變數：POETRY_VIRTUALENVS_PATH

將建立虛擬環境的目錄。

請注意

此設定控管全域虛擬環境儲存路徑。在本地層級上，不太會用到。若要將虛擬環境儲存在專案根目錄，請查看 virtualenvs.in-project。

`virtualenvs.prefer-active-python`（試驗性質）#

類型: 布林值

預設值: false

環境變數：POETRY_VIRTUALENVS_PREFER_ACTIVE_PYTHON

於 1.2.0 引入

使用當前已啟用的 Python 版本建立新的虛擬環境。若設為 false，則會使用 Poetry 安裝期間的 Python 版本。

`virtualenvs.prompt` #

類型：文字

預設值：{project_name}-py{python_version}

環境變數：POETRY_VIRTUALENVS_PROMPT

於 1.2.0 引入

格式化字串，定義在虛擬環境啟用時要顯示的提示字串。變數 project_name 與 python_version 可供格式化使用。

`repositories.<name>.url` #

類型：文字

環境變數：POETRY_REPOSITORIES_<NAME>_URL

設定 <name> 的存放庫 URL。

進一步瞭解，請參閱可發布存放庫。

`http-basic.<name>.[username|password]` #

類型：文字

環境變數：POETRY_HTTP_BASIC_<NAME>_USERNAME、POETRY_HTTP_BASIC_<NAME>_PASSWORD

設定 <name> 的存放庫認證資訊（username 與 password）。進一步瞭解，請參閱存放庫 - 設定認證資訊。

`pypi-token.<name>` #

類型：文字

環境變數：POETRY_PYPI_TOKEN_<NAME>

設定 <name> 的存放庫認證資訊（使用 API 令牌）。進一步瞭解，請參閱存放庫 - 設定認證資訊。

`certificates.<name>.cert` #

類型: 字串 | 布林值

環境變數：POETRY_CERTIFICATES_<NAME>_CERT

設定存放庫 <name> 的自訂驗證機構。進一步瞭解，請參閱存放庫 - 設定認證資訊 - 自訂驗證機構。

如果應略過此存放庫的 TLS 憑證驗證，此設定可以設為 false。

`certificates.<name>.client-cert` #

類型：文字

環境變數：POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

設定存放庫 <name> 的用戶端憑證。進一步瞭解，請參閱存放庫 - 設定認證資訊 - 自訂驗證機構。

`keyring.enabled` #

類型: 布林值

預設值: true

環境變數：POETRY_KEYRING_ENABLED

啟用系統鑰匙圈來儲存憑證。有關更多資訊，請參閱儲存庫 - 設定憑證。

組態

設定 #

本機設定 #

列出目前設定 #

顯示單一的組態設定 #

加入或更新組態設定 #

移除特定設定 #

使用環境變數 #

預設目錄 #

組態目錄 #

資料目錄 #

快取目錄 #

可用設定 #

cache-dir #

experimental.system-git-client #

installer.max-workers #

installer.modern-installation #

installer.no-binary #

installer.parallel #

solver.lazy-wheel #

virtualenvs.create #

virtualenvs.in-project #

virtualenvs.options.always-copy #

virtualenvs.options.no-pip #

virtualenvs.options.no-setuptools #

virtualenvs.options.system-site-packages #

virtualenvs.path #

virtualenvs.prefer-active-python（試驗性質）#

virtualenvs.prompt #

repositories.<name>.url #

http-basic.<name>.[username|password] #

pypi-token.<name> #

certificates.<name>.cert #

certificates.<name>.client-cert #

keyring.enabled #

`cache-dir` #

`experimental.system-git-client` #

`installer.max-workers` #

`installer.modern-installation` #

`installer.no-binary` #

`installer.parallel` #

`solver.lazy-wheel` #

`virtualenvs.create` #

`virtualenvs.in-project` #

`virtualenvs.options.always-copy` #

`virtualenvs.options.no-pip` #

`virtualenvs.options.no-setuptools` #

`virtualenvs.options.system-site-packages` #

`virtualenvs.path` #

`virtualenvs.prefer-active-python`（試驗性質）#

`virtualenvs.prompt` #

`repositories.<name>.url` #

`http-basic.<name>.[username|password]` #

`pypi-token.<name>` #

`certificates.<name>.cert` #

`certificates.<name>.client-cert` #

`keyring.enabled` #