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 be 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: C:\Users\<username>\AppData\Roaming\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

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/Preferences/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: %APPDATA%\pypoetry\Cache
• MacOS: ~/Library/Caches/pypoetry

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

Available settings #

cache-dir #

Type: string

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

installer.parallel #

Type: boolean

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

installer.max-workers #

Type: int

Set the maximum number of workers while using the parallel installer. Defaults to number_of_cores + 4. The number_of_cores is determined by os.cpu_count(). If this raises a NotImplentedError 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.

installer.no-binary #

Type: string | bool

Introduced in 1.2.0

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

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

export POETRY_INSTALLER_NO_BINARY=:all:

virtualenvs.create #

Type: boolean

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

If set to false, poetry will install dependencies into the current python environment.

virtualenvs.in-project #

Type: boolean

Create the virtualenv inside the project’s root directory. Defaults to None.

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

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

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

virtualenvs.path #

Type: string

Directory where virtual environments will be created. Defaults to {cache-dir}/virtualenvs ({cache-dir}\virtualenvs on Windows).

virtualenvs.prompt #

Type: string

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. Defaults to "{project_name}-py{python_version}".

virtualenvs.options.always-copy #

Type: boolean

If set to true the --always-copy parameter is passed to virtualenv on creation of the venv. Thus all needed files are copied into the venv instead of symlinked. Defaults to false.

virtualenvs.options.no-pip #

Type: boolean

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

virtualenvs.options.no-setuptools #

Type: boolean

If set to true the --no-setuptools parameter is passed to virtualenv on creation of the venv. 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. Defaults to false.

virtualenvs.options.system-site-packages #

Type: boolean

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

virtualenvs.prefer-active-python (experimental) #

Type: boolean

Use currently activated Python version to create a new venv. Defaults to false, which means Python version used during Poetry installation is used.

repositories.<name> #

Type: string

Set a new alternative repository. See Repositories for more information.

http-basic.<name>: #

Types: string, string

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

pypi-token.<name>: #

Type: string

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

certificates.<name>.cert: #

Type: string | bool

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

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