poetry-config

List current configuration

$ poetry config --list

$ poetry config [config_key] --unset

$ poetry config [config_key]

$ poetry config [config_key] [config_value]

$ poetry config --migrate

$ poetry config --local

poetry config [options] [setting-key] [setting-value]

--list
    Lists all current configuration settings, including their values and the scope (global/local) from which they originate.

--local
    Specifies that the configuration setting should be applied to or retrieved from the local project's configuration file (e.g., pyproject.toml or poetry.toml in the project root).

--global
    Specifies that the configuration setting should be applied to or retrieved from the global Poetry configuration file (typically located in the user's home directory).

--unset, --rm
    Unsets or removes a specified configuration setting. If no scope (--local or --global) is provided, it defaults to unsetting locally.

--repo, --repository
    Manages configuration settings specific to a defined repository, typically used for configuring repository URLs or authentication credentials. Note: --repository is deprecated; use --repo instead.

-h, --help
    Displays help information for the config command, showing available options and usage patterns.

--config path
    Specifies an alternative path to the configuration file that Poetry should use for the current command execution.

-q, --quiet
    Suppresses all output messages, making the command execution silent.

-v, --verbose
    Increases the verbosity of messages. Can be used up to three times (-vvv) for more detailed output, including debug information.

The poetry config command is an essential tool for inspecting, modifying, and unsetting various configuration settings within the Poetry Python dependency management ecosystem. These settings dictate aspects such as virtual environment creation and location, package installation behavior, repository credentials, and general workflow preferences.

Users can leverage this command to list all current configurations, retrieve the value of a specific setting, or update a setting with a new value. It supports managing configurations at different scopes: global (affecting all Poetry projects), local (specific to the current project), and for defined repositories. This flexibility allows users to tailor Poetry's behavior precisely to their development environment and project requirements, ensuring consistency and efficiency.

The --repository option is deprecated; users should prefer --repo. When setting configuration values, local settings (applied with --local) will always take precedence over global settings (applied with --global).

Care should be exercised when managing sensitive information, such as API tokens; Poetry encrypts these in its configuration files, but awareness of access and scope is still crucial. Always ensure you understand the intended scope of the setting you are modifying to prevent unintended consequences across projects.

Poetry configuration can be managed at different levels, each affecting the tool's behavior in specific contexts:

• Global: Settings applied using --global affect all Poetry projects on the system. These are typically stored in Poetry's global configuration file (e.g., ~/.config/pypoetry/config.toml on Linux).
• Local: Settings applied using --local affect only the current project. They are stored within the project's pyproject.toml or a dedicated poetry.toml file. Local settings take precedence over global settings.
• Repository: Specific settings for defined package repositories, primarily for authentication details, are stored within the global configuration but are tied to specific repository names.

The poetry config command offers various patterns for interaction:

• Display all settings: poetry config --list
• Get a specific setting: poetry config setting-key (e.g., poetry config virtualenvs.create)
• Set a setting: poetry config setting-key setting-value (e.g., poetry config virtualenvs.in-project true --local)
• Unset a setting: poetry config --unset setting-key (e.g., poetry config --unset http-basic.example.username --global)

Poetry, created by Sébastien Eustace in 2017, quickly established itself as a modern Python dependency management tool. The config command has been a foundational component since Poetry's early development, providing users with the necessary means to customize its behavior. Its features have evolved alongside Poetry itself, particularly in areas such as virtual environment management, secure repository authentication, and support for new installation methodologies, reflecting the dynamic needs of Python project development.

poetry(1), pip(1)