Config File Locator

Poetry config file locations

This page covers Poetry runtime configuration, not project metadata and dependencies in pyproject.toml. Environment variables take precedence over project-local poetry.toml, which takes precedence over the user config.toml and Poetry defaults. POETRY_CONFIG_DIR replaces the platform default user configuration directory. auth.toml and the system keyring store repository credentials separately from this settings precedence.

  1. Project local level

    Local overrides

    Poetry runtime settings for one project. Replace <project> with the project root.

    Config file location
    <project>/poetry.toml
    Created or updated by poetry config --local. This file is separate from pyproject.toml.
    Commands
    vi "<project>/poetry.toml"

  2. User level

    User defaults

    User-wide settings and repository credentials. POETRY_CONFIG_DIR replaces the XDG-based directory when set.

    Config file location
    ~/.config/pypoetry/config.toml
    Default user settings when XDG_CONFIG_HOME and POETRY_CONFIG_DIR are unset.
    ~/.config/pypoetry/auth.toml
    Default credential fallback when XDG_CONFIG_HOME and POETRY_CONFIG_DIR are unset.
    $XDG_CONFIG_HOME/pypoetry/config.toml
    Alternative user settings path when XDG_CONFIG_HOME is set and POETRY_CONFIG_DIR is unset.
    $XDG_CONFIG_HOME/pypoetry/auth.toml
    Alternative credential file path when XDG_CONFIG_HOME is set and POETRY_CONFIG_DIR is unset.
    $POETRY_CONFIG_DIR/config.toml
    Alternative user settings path when POETRY_CONFIG_DIR is set.
    $POETRY_CONFIG_DIR/auth.toml
    Alternative credential file path when POETRY_CONFIG_DIR is set.
    Commands
    vi "$HOME/.config/pypoetry/config.toml"
    vi "$XDG_CONFIG_HOME/pypoetry/config.toml"
    vi "$POETRY_CONFIG_DIR/config.toml"
Inspect configuration
poetry config --list
Official Poetry documentation