Home Poetry logo

Configuration

Configuration #

Poetry can be configured via the config command (see more about its usage here) or directly in the config.toml file that will be automatically created when you first run that command. This file can typically be found in one of the following directories:

  • macOS: ~/Library/Application Support/pypoetry
  • Windows: %APPDATA%\pypoetry

For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default ~/.config/pypoetry.

Local configuration #

Poetry also provides the ability to have settings that are specific to a project by passing the --local option to the config command.

poetry config virtualenvs.create false --local
Note
Your local configuration of Poetry application is stored in the poetry.toml file, which is separate from pyproject.toml.
Warning
Be mindful about checking in this file into your repository since it may contain user-specific or sensitive information.

Listing the current configuration #

To list the current configuration you can use the --list option of the config command:

poetry config --list

which will give you something similar to this:

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}"

Displaying a single configuration setting #

If you want to see the value of a specific setting, you can give its name to the config command

poetry config virtualenvs.path

For a full list of the supported settings see Available settings.

Adding or updating a configuration setting #

To change or otherwise add a new configuration setting, you can pass a value after the setting’s name:

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

For a full list of the supported settings see Available settings.

Removing a specific setting #

If you want to remove a previously set setting, you can use the --unset option:

poetry config virtualenvs.path --unset

The setting will then retrieve its default value.

Using environment variables #

Sometimes, in particular when using Poetry with CI tools, it’s easier to use environment variables and not have to execute configuration commands.

Poetry supports this and any setting can be set by using environment variables.

The environment variables must be prefixed by POETRY_ and are comprised of the uppercase name of the setting and with dots and dashes replaced by underscore, here is an example:

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

This also works for secret settings, like credentials:

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

Default Directories #

Poetry uses the following default directories:

Config Directory #

  • Linux: $XDG_CONFIG_HOME/pypoetry or ~/.config/pypoetry
  • Windows: %APPDATA%\pypoetry
  • MacOS: ~/Library/Application Support/pypoetry

You can override the Config directory by setting the POETRY_CONFIG_DIR environment variable.

Data Directory #

  • Linux: $XDG_DATA_HOME/pypoetry or ~/.local/share/pypoetry
  • Windows: %APPDATA%\pypoetry
  • MacOS: ~/Library/Application Support/pypoetry

You can override the Data directory by setting the POETRY_DATA_DIR or POETRY_HOME environment variables. If POETRY_HOME is set, it will be given higher priority.

Cache Directory #

  • Linux: $XDG_CACHE_HOME/pypoetry or ~/.cache/pypoetry
  • Windows: %LOCALAPPDATA%\pypoetry
  • MacOS: ~/Library/Caches/pypoetry

You can override the Cache directory by setting the POETRY_CACHE_DIR environment variable.

Available settings #

cache-dir #

Type: string

Environment Variable: POETRY_CACHE_DIR

The path to the cache directory used by Poetry.

Defaults to one of the following directories:

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

experimental.system-git-client #

Type: boolean

Default: false

Environment Variable: POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT

Introduced in 1.2.0

Use system git client backend for git related tasks.

Poetry uses dulwich by default for git related tasks to not rely on the availability of a git client.

If you encounter any problems with it, set to true to use the system git backend.

installer.max-workers #

Type: int

Default: number_of_cores + 4

Environment Variable: POETRY_INSTALLER_MAX_WORKERS

Introduced in 1.2.0

Set the maximum number of workers while using the parallel installer. The number_of_cores is determined by os.cpu_count(). If this raises a NotImplementedError exception, number_of_cores is assumed to be 1.

If this configuration parameter is set to a value greater than number_of_cores + 4, the number of maximum workers is still limited at number_of_cores + 4.

Note
This configuration is ignored when installer.parallel is set to false.

installer.modern-installation #

Type: boolean

Default: true

Environment Variable: POETRY_INSTALLER_MODERN_INSTALLATION

Introduced in 1.4.0

Use a more modern and faster method for package installation.

If this causes issues, you can disable it by setting it to false and report the problems you encounter on the issue tracker.

installer.no-binary #

Type: string | boolean

Default: false

Environment Variable: POETRY_INSTALLER_NO_BINARY

Introduced in 1.2.0

When set this configuration allows users to configure package distribution format policy for all or specific packages.

Configuration Description
:all: or true Disallow binary distributions for all packages.
:none: or false Allow binary distributions for all packages.
package[,package,..] Disallow binary distributions for specified packages only.
Note
As with all configurations described here, this is a user specific configuration. This means that this is not taken into consideration when a lockfile is generated or dependencies are resolved. This is applied only when selecting which distribution for dependency should be installed into a Poetry managed environment.
Note

For project specific usage, it is recommended that this be configured with the --local.

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

For CI or container environments using environment variable to configure this might be useful.

export POETRY_INSTALLER_NO_BINARY=:all:
Warning
Unless this is required system-wide, if configured globally, you could encounter slower install times across all your projects if incorrectly set.

installer.parallel #

Type: boolean

Default: true

Environment Variable: POETRY_INSTALLER_PARALLEL

Introduced in 1.1.4

Use parallel execution when using the new (>=1.1.0) installer.

solver.lazy-wheel #

Type: boolean

Default: true

Environment Variable: POETRY_SOLVER_LAZY_WHEEL

Introduced in 1.8.0

Do not download entire wheels to extract metadata but use HTTP range requests to only download the METADATA files of wheels. Especially with slow network connections this setting can speed up dependency resolution significantly. If the cache has already been filled or the server does not support HTTP range requests, this setting makes no difference.

virtualenvs.create #

Type: boolean

Default: true

Environment Variable: POETRY_VIRTUALENVS_CREATE

Create a new virtual environment if one doesn’t already exist.

If set to false, Poetry will not create a new virtual environment. If it detects an already enabled virtual environment or an existing one in {cache-dir}/virtualenvs or {project-dir}/.venv it will install dependencies into them, otherwise it will install dependencies into the systems python environment.

Note
If Poetry detects it’s running within an activated virtual environment, it will never create a new virtual environment, regardless of the value set for virtualenvs.create.
Note

Be aware that installing dependencies into the system environment likely upgrade or uninstall existing packages and thus break other applications. Installing additional Python packages after installing the project might break the Poetry project in return.

This is why it is recommended to always create a virtual environment. This is also true in Docker containers, as they might contain additional Python packages as well.

virtualenvs.in-project #

Type: boolean

Default: None

Environment Variable: POETRY_VIRTUALENVS_IN_PROJECT

Create the virtualenv inside the project’s root directory.

If not set explicitly, poetry by default will create a virtual environment under {cache-dir}/virtualenvs or use the {project-dir}/.venv directory if one already exists.

If set to true, the virtualenv will be created and expected in a folder named .venv within the root directory of the project.

Note

If a virtual environment has already been created for the project under {cache-dir}/virtualenvs, setting this variable to true will not cause poetry to create or use a local virtual environment.

In order for this setting to take effect for a project already in that state, you must delete the virtual environment folder located in {cache-dir}/virtualenvs.

You can find out where the current project’s virtual environment (if there is one) is stored with the command poetry env info --path.

If set to false, poetry will ignore any existing .venv directory.

virtualenvs.options.always-copy #

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

Introduced in 1.2.0

If set to true the --always-copy parameter is passed to virtualenv on creation of the virtual environment, so that all needed files are copied into it instead of symlinked.

virtualenvs.options.no-pip #

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_NO_PIP

Introduced in 1.2.0

If set to true the --no-pip parameter is passed to virtualenv on creation of the virtual environment. This means when a new virtual environment is created, pip will not be installed in the environment.

Note

Poetry, for its internal operations, uses the pip wheel embedded in the virtualenv package installed as a dependency in Poetry’s runtime environment. If a user runs poetry run pip when this option is set to true, the pip the embedded instance of pip is used.

You can safely set this, along with no-setuptools, to true, if you desire a virtual environment with no additional packages. This is desirable for production environments.

virtualenvs.options.no-setuptools #

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_NO_SETUPTOOLS

Introduced in 1.2.0

If set to true the --no-setuptools parameter is passed to virtualenv on creation of the virtual environment. This means when a new virtual environment is created, setuptools will not be installed in the environment. Poetry, for its internal operations, does not require setuptools and this can safely be set to true.

For environments using python 3.12 or later, virtualenv defaults to not installing setuptools when creating a virtual environment. In such environments this poetry configuration option therefore has no effect: setuptools is not installed either way. If your project relies on setuptools, you should declare it as a dependency.

Warning
Some development tools like IDEs, make an assumption that setuptools (and other) packages are always present and available within a virtual environment. This can cause some features in these tools to not work as expected.

virtualenvs.options.system-site-packages #

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

Give the virtual environment access to the system site-packages directory. Applies on virtualenv creation.

virtualenvs.path #

Type: string

Default: {cache-dir}/virtualenvs

Environment Variable: POETRY_VIRTUALENVS_PATH

Directory where virtual environments will be created.

Note
This setting controls the global virtual environment storage path. It most likely will not be useful at the local level. To store virtual environments in the project root, see virtualenvs.in-project.

virtualenvs.prefer-active-python (experimental) #

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_PREFER_ACTIVE_PYTHON

Introduced in 1.2.0

Use currently activated Python version to create a new virtual environment. If set to false, Python version used during Poetry installation is used.

virtualenvs.prompt #

Type: string

Default: {project_name}-py{python_version}

Environment Variable: POETRY_VIRTUALENVS_PROMPT

Introduced in 1.2.0

Format string defining the prompt to be displayed when the virtual environment is activated. The variables project_name and python_version are available for formatting.

repositories.<name>.url #

Type: string

Environment Variable: POETRY_REPOSITORIES_<NAME>_URL

Set the repository URL for <name>.

See Publishable Repositories for more information.

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

Type: string

Environment Variables: POETRY_HTTP_BASIC_<NAME>_USERNAME, POETRY_HTTP_BASIC_<NAME>_PASSWORD

Set repository credentials (username and password) for <name>. See Repositories - Configuring credentials for more information.

pypi-token.<name>: #

Type: string

Environment Variable: POETRY_PYPI_TOKEN_<NAME>

Set repository credentials (using an API token) for <name>. See Repositories - Configuring credentials for more information.

certificates.<name>.cert: #

Type: string | boolean

Environment Variable: POETRY_CERTIFICATES_<NAME>_CERT

Set custom certificate authority for repository <name>. See Repositories - Configuring credentials - Custom certificate authority for more information.

This configuration can be set to false, if TLS certificate verification should be skipped for this repository.

certificates.<name>.client-cert: #

Type: string

Environment Variable: POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

Set client certificate for repository <name>. See Repositories - Configuring credentials - Custom certificate authority for more information.

keyring.enabled: #

Type: boolean

Default: true

Environment Variable: POETRY_KEYRING_ENABLED

Enable the system keyring for storing credentials. See Repositories - Configuring credentials for more information.