Configuration

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

Poetry’s own behaviour (where environments go, how the installer works, which credentials to use) is set with poetry config, in files, or with POETRY_* environment variables. Project metadata and dependencies are not configuration: they belong in pyproject.toml (see pyproject.toml & Project Metadata). This page is written against Poetry 2.5.1. The examples ran on 2026-10-22 on Linux with CPython 3.14.6, with POETRY_CONFIG_DIR, POETRY_CACHE_DIR and POETRY_DATA_DIR pointed at empty scratch directories (shortened to …).

Where settings live

Source Written by Notes

Environment variables

your shell or CI

POETRY_ followed by the setting name in upper case, with dots and dashes replaced by underscores: virtualenvs.in-project is POETRY_VIRTUALENVS_IN_PROJECT.

poetry.toml in the project

poetry config --local …

Project-local settings, next to pyproject.toml. It can hold user-specific values; think before committing it.

config.toml in the config directory

poetry config …

Global (per-user) settings.

auth.toml in the config directory, or the system keyring

poetry config http-basic.<name> …, pypi-token.<name> …

Credentials only; see Credentials and certificates.

When a setting is defined in several places, the precedence is, from highest to lowest: environment variables, the local poetry.toml, the global config.toml, the default value. Credentials from auth.toml and the keyring are also overridden by environment variables.

Environment variables override poetry.toml, which overrides config.toml, which overrides the default; credentials come from environment variables, the keyring or auth.toml

Source: Poetry: Configuration sources, Local configuration.

Default directories

Directory Linux macOS Windows Override

Config (config.toml, auth.toml)

$XDG_CONFIG_HOME/pypoetry or ~/.config/pypoetry

~/Library/Application Support/pypoetry

%APPDATA%\pypoetry

POETRY_CONFIG_DIR

Data (installer-managed Poetry, poetry python interpreters)

$XDG_DATA_HOME/pypoetry or ~/.local/share/pypoetry

~/Library/Application Support/pypoetry

%APPDATA%\pypoetry

POETRY_DATA_DIR, or POETRY_HOME (which wins if both are set)

Cache (downloads, virtualenvs/)

$XDG_CACHE_HOME/pypoetry or ~/.cache/pypoetry

~/Library/Caches/pypoetry

%LOCALAPPDATA%\pypoetry

POETRY_CACHE_DIR

Source: Poetry: Default directories, Config directory, Data directory, Cache directory.

poetry config

Listing and reading

poetry config --list
cache-dir = "/root/.cache/pypoetry"  # …/cache
data-dir = "/root/.local/share/pypoetry"  # …/data
installer.builtin-uninstall = false
installer.max-workers = null
installer.no-binary = null
installer.only-binary = null
installer.parallel = true
installer.re-resolve = false
keyring.enabled = true
python.installation-dir = "{data-dir}/python"  # …/data/python
requests.max-retries = 0
solver.lazy-wheel = true
solver.min-release-age = 0
solver.min-release-age-exclude = null
solver.min-release-age-exclude-source = null
system-git-client = false
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # …/cache/virtualenvs
virtualenvs.prompt = "{project_name}-py{python_version}"
virtualenvs.use-poetry-python = false

That is the complete list of 24 plain settings in Poetry 2.5.1, with their defaults (the families keyed by a name, such as repositories.<name>.url, only appear once set). The comment after a path shows the value actually in effect: here cache-dir reports the platform default but the POETRY_CACHE_DIR override after the #. Give a single name to read one value:

poetry config virtualenvs.path
…/cache/virtualenvs

Source: Poetry: Listing the current configuration, Displaying a single configuration setting, Available settings.

Setting, local settings and unsetting

poetry config virtualenvs.in-project true
poetry config --local virtualenvs.create false
cat "$POETRY_CONFIG_DIR/config.toml" poetry.toml
[virtualenvs]
in-project = true
[virtualenvs]
create = false

The first block is the global config.toml, the second the project’s poetry.toml. Environment variables beat both:

POETRY_VIRTUALENVS_CREATE=true poetry config virtualenvs.create
poetry config virtualenvs.create
poetry config --local virtualenvs.create --unset
poetry config virtualenvs.create
true
false
true

--unset removes the value from the chosen file, so the next source down (here the default) applies again; the emptied poetry.toml is left in place. Boolean environment variables accept true/1 for true; 0, false, no and an empty string all read as false when tried. Mistakes fail with exit code 1:

poetry config virtualenvs.creat true
poetry config virtualenvs.create maybe
Setting virtualenvs.creat does not exist
"maybe" is an invalid value for virtualenvs.create

A value that starts with a dash would be read as an option; put -- before the setting name: poetry config -- http-basic.ci ci-user -starts-with-dash. Without the -- the same command fails with The option "s" does not exist (exit code 1).

Source: Poetry: Adding or updating a configuration setting, Local configuration, Removing a specific setting, Using environment variables.

Migrating renamed settings

poetry config --migrate (and --migrate --local for poetry.toml) rewrites settings that a newer Poetry has renamed, such as experimental.system-git-client to system-git-client in 2.0. With nothing to change it prints:

Checking for required migrations ...
Already up to date.

Source: Poetry: Migrate outdated configs, Poetry CLI: config.

Available settings

Settings marked experimental can change in later releases. Paths may use {cache-dir}, {data-dir} and, for the prompt, {project_name} and {python_version}.

Setting Type Default Environment variable Meaning

cache-dir

string

platform cache directory

POETRY_CACHE_DIR

Where downloads, the artifact cache and (by default) virtual environments go.

data-dir

string

platform data directory

POETRY_DATA_DIR

Where data such as Poetry-managed Pythons go.

installer.max-workers

int

number of cores + 4

POETRY_INSTALLER_MAX_WORKERS

Upper limit of parallel installer workers (capped at cores + 4). Since 1.2.0.

installer.no-binary

string or bool

false

POETRY_INSTALLER_NO_BINARY

Refuse wheels: :all:/true, :none:/false, or a comma-separated list of packages. Since 1.2.0.

installer.only-binary

string or bool

false

POETRY_INSTALLER_ONLY_BINARY

Refuse sdists, same values. Explicit package names beat :all: when both settings are set. Since 2.0.0.

installer.parallel

bool

true

POETRY_INSTALLER_PARALLEL

Install in parallel. Since 1.1.4.

installer.builtin-uninstall

bool

false

POETRY_INSTALLER_BUILTIN_UNINSTALL

Uninstall with Poetry’s own routine instead of a pip uninstall subprocess. Since 2.5.0.

installer.build-config-settings.<package>

JSON object

none

POETRY_INSTALLER_BUILD_CONFIG_SETTINGS_<package>

PEP 517 config settings passed to the build backend when that package has to be built. Experimental, since 2.1.0.

installer.re-resolve

bool

false

POETRY_INSTALLER_RE_RESOLVE

false: with a lock file of version 2.1 or later, evaluate the locked markers instead of resolving again. Since 2.0.0; default changed from true to false in 2.3.0.

requests.max-retries

int

0

POETRY_REQUESTS_MAX_RETRIES

Retries on an unstable network. Since 2.0.0.

python.installation-dir

string

{data-dir}/python

POETRY_PYTHON_INSTALLATION_DIR

Where poetry python install puts interpreters. Since 2.1.0.

solver.lazy-wheel

bool

true

POETRY_SOLVER_LAZY_WHEEL

Fetch only a wheel’s METADATA with HTTP range requests. Since 1.8.0.

solver.min-release-age

int (days)

0

POETRY_SOLVER_MIN_RELEASE_AGE

Ignore releases with any file uploaded fewer than this many days ago. Since 2.4.0.

solver.min-release-age-exclude

string

not set

POETRY_SOLVER_MIN_RELEASE_AGE_EXCLUDE

Comma-separated packages exempt from the age filter. Since 2.4.0.

solver.min-release-age-exclude-source

string

not set

POETRY_SOLVER_MIN_RELEASE_AGE_EXCLUDE_SOURCE

Comma-separated source names or URLs exempt from the age filter. Since 2.4.0.

system-git-client

bool

false

POETRY_SYSTEM_GIT_CLIENT

Use the git command instead of the bundled Dulwich library. Since 1.2.0 as experimental.system-git-client, renamed in 2.0.0.

virtualenvs.create

bool

true

POETRY_VIRTUALENVS_CREATE

Create an environment if none exists; false installs into the current interpreter.

virtualenvs.in-project

bool

none

POETRY_VIRTUALENVS_IN_PROJECT

true: create and expect .venv in the project; false: ignore an existing .venv; unset: use .venv if it exists, otherwise the cache.

virtualenvs.options.always-copy

bool

false

POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

Pass --always-copy to virtualenv. Since 1.2.0.

virtualenvs.options.no-pip

bool

false

POETRY_VIRTUALENVS_OPTIONS_NO_PIP

Create environments without pip. Since 1.2.0.

virtualenvs.options.system-site-packages

bool

false

POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

Give the environment access to the system site-packages.

virtualenvs.path

string

{cache-dir}/virtualenvs

POETRY_VIRTUALENVS_PATH

Where environments are created when not in the project.

virtualenvs.prompt

string

{project_name}-py{python_version}

POETRY_VIRTUALENVS_PROMPT

Prompt shown when the environment is activated. Since 1.2.0.

virtualenvs.use-poetry-python

bool

false

POETRY_VIRTUALENVS_USE_POETRY_PYTHON

Create environments from the Python Poetry was installed with instead of the active python. Since 2.0.0.

repositories.<name>.url

string

none

POETRY_REPOSITORIES_<NAME>_URL

URL of a repository to publish to.

http-basic.<name>.username, .password

string

none

POETRY_HTTP_BASIC_<NAME>_USERNAME, POETRY_HTTP_BASIC_<NAME>_PASSWORD

Username and password for a source or repository.

pypi-token.<name>

string

none

POETRY_PYPI_TOKEN_<NAME>

API token for a repository (pypi-token.pypi for PyPI).

certificates.<name>.cert

string or bool

none

POETRY_CERTIFICATES_<NAME>_CERT

CA bundle for that repository; false skips TLS verification.

certificates.<name>.client-cert

string

none

POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

Client certificate for mutual TLS.

keyring.enabled

bool

true

POETRY_KEYRING_ENABLED

Store credentials in the system keyring.

Notes on the settings that cause most surprises:

  • installer.no-binary, installer.only-binary and installer.build-config-settings are user settings: they only decide which file is installed into a Poetry-managed environment, never what goes into poetry.lock. Set them with --local for one project, or as environment variables in CI. A global installer.no-binary = :all: slows every project down.

  • virtualenvs.in-project = true does not move an environment that already exists in the cache; remove it with poetry env remove first (see Managing Environments).

  • solver.min-release-age (2.4.0) is a supply-chain guard; the filter only works for sources that publish upload times. pip’s counterpart is --uploaded-prior-to (see Supply-Chain Security).

  • installer.re-resolve is why a Poetry 2.3+ install no longer resolves again from a lock file; see Lock File, Install, Update & Sync.

  • Values are read and written as text: poetry config installer.no-binary ':all:' reads back as [":all:"], and poetry config installer.build-config-settings.grpcio '{"CC": "gcc"}' reads back the JSON unchanged.

One more knob is not a setting: the HTTP timeout is 15 seconds, like pip’s, and only the experimental environment variable POETRY_REQUESTS_TIMEOUT (seconds) changes it.

Source: Poetry: Available settings, installer.max-workers, solver.lazy-wheel, Poetry FAQ: My requests are timing out!, installer.no-binary, installer.re-resolve, solver.min-release-age, virtualenvs.in-project.

Credentials and certificates

http-basic and pypi-token values are not stored in config.toml. They go to the system keyring when one is available, or else, with a warning, to the plaintext auth.toml in the config directory. With the keyring disabled:

export POETRY_KEYRING_ENABLED=false
poetry config repositories.birdwatch http://127.0.0.1:8080/
poetry config http-basic.birdwatch alice "$BIRDWATCH_PASSWORD"
ls "$POETRY_CONFIG_DIR"
Using a plaintext file to store credentials
auth.toml
config.toml

auth.toml then holds a [http-basic.birdwatch] table with username and password. Give only the username and Poetry asks for the password on the terminal (where no terminal is attached it keeps asking, so a CI job hangs: always use POETRY_HTTP_BASIC_<NAME>_PASSWORD there). Reading a credential back is refused with Expected a value for http-basic.birdwatch setting. Sources, repositories and certificates are covered in depth on Repositories & Package Sources.

Source: Poetry: Configuring credentials, http-basic, keyring.enabled.

Compared with pip

Concern Poetry pip

Files

config.toml (global), poetry.toml (project), TOML

pip.conf/pip.ini at global, user and site level, INI

Environment variables

POETRY_<SETTING>

PIP_<OPTION> for every command-line option

Command

poetry config [--local] name [value] | --unset | --list

pip config [--global|--user|--site] list|get|set|unset|edit|debug

Credentials

keyring or auth.toml, POETRY_HTTP_BASIC_*

keyring, .netrc or the URL

See pip: Configuration.

References