From e78df63f8c48fc168c06dcd605c9383a8175732a Mon Sep 17 00:00:00 2001 From: Dr Alex Mitre Date: Thu, 5 Mar 2026 14:10:39 -0600 Subject: [PATCH 1/2] docs: clarify configuration source precedence Add a section to configuration docs that explains precedence among environment variables, local config, global config, and defaults. --- docs/configuration.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index abe4ea38ec8..8b389537ea3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,6 +40,20 @@ If a setting is defined in both `poetry.toml` (local/project) and `config.toml` the local/project configuration takes precedence over the global configuration. {{% /note %}} +## Configuration sources + +When a setting is set in multiple places, Poetry applies the following precedence +(from highest to lowest): + +1. Environment variables (for example, `POETRY_VIRTUALENVS_CREATE`) +2. The local `poetry.toml` file (created with `poetry config --local`) +3. The global `config.toml` file +4. The setting's default value + +For repository credentials (`http-basic.*`, `pypi-token.*`), Poetry may also read +from `auth.toml` and the system keyring. Environment variables still take +precedence over file-based values. + {{% warning %}} Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information. {{% /warning %}} From 2dca96da48dbd2c7eebe3ff3e3fe84036d4aa5a4 Mon Sep 17 00:00:00 2001 From: mitre88 Date: Fri, 17 Apr 2026 20:23:42 -0600 Subject: [PATCH 2/2] docs: move Configuration Sources section after env vars, add link to Repositories docs Address review feedback from @radoering: - Move 'Configuration sources' section after 'Using environment variables' - Move warning back under 'Local configuration' - Add link to Repositories docs for auth.toml/keyring details --- docs/configuration.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8b389537ea3..d1d8098f895 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,20 +40,6 @@ If a setting is defined in both `poetry.toml` (local/project) and `config.toml` the local/project configuration takes precedence over the global configuration. {{% /note %}} -## Configuration sources - -When a setting is set in multiple places, Poetry applies the following precedence -(from highest to lowest): - -1. Environment variables (for example, `POETRY_VIRTUALENVS_CREATE`) -2. The local `poetry.toml` file (created with `poetry config --local`) -3. The global `config.toml` file -4. The setting's default value - -For repository credentials (`http-basic.*`, `pypi-token.*`), Poetry may also read -from `auth.toml` and the system keyring. Environment variables still take -precedence over file-based values. - {{% warning %}} Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information. {{% /warning %}} @@ -133,6 +119,20 @@ This also works for secret settings, like credentials: export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret ``` +## Configuration sources + +When a setting is set in multiple places, Poetry applies the following precedence +(from highest to lowest): + +1. Environment variables (for example, `POETRY_VIRTUALENVS_CREATE`) +2. The local `poetry.toml` file (created with `poetry config --local`) +3. The global `config.toml` file +4. The setting's default value + +For repository credentials (`http-basic.*`, `pypi-token.*`), Poetry may also read +from `auth.toml` and the system keyring (for details see [Repositories]({{< relref "repositories" >}})). +Environment variables still take precedence over file-based values. + ## Migrate outdated configs If Poetry renames or remove config options it might be necessary to migrate explicit set options. This is possible