pypa/pip · error · ConfigurationError

Key does not contain dot separated section and key. Perhaps

Error message

Key does not contain dot separated section and key. Perhaps you wanted to use 'global.{name}' instead?

What it means

Raised as ConfigurationError in _disassemble_key() at configuration.py:60-65 when the provided config key has no '.' separator. pip's config API requires keys in 'section.name' form (e.g. 'global.index-url'); a bare name like 'index-url' is ambiguous and pip suggests prefixing it with a section such as 'global.'.

Source

Thrown at src/pip/_internal/configuration.py:65

logger = getLogger(__name__)


# NOTE: Maybe use the optionx attribute to normalize keynames.
def _normalize_name(name: str) -> str:
    """Make a name consistent regardless of source (environment or file)"""
    name = name.lower().replace("_", "-")
    name = name.removeprefix("--")  # only prefer long opts
    return name


def _disassemble_key(name: str) -> list[str]:
    if "." not in name:
        error_message = (
            "Key does not contain dot separated section and key. "
            f"Perhaps you wanted to use 'global.{name}' instead?"
        )
        raise ConfigurationError(error_message)
    return name.split(".", 1)


def get_configuration_files() -> dict[Kind, list[str]]:
    global_config_files = [
        os.path.join(path, CONFIG_BASENAME) for path in appdirs.site_config_dirs("pip")
    ]

    site_config_file = os.path.join(sys.prefix, CONFIG_BASENAME)
    legacy_config_file = os.path.join(
        os.path.expanduser("~"),
        "pip" if WINDOWS else ".pip",
        CONFIG_BASENAME,
    )
    new_config_file = os.path.join(appdirs.user_config_dir("pip"), CONFIG_BASENAME)
    return {
        kinds.GLOBAL: global_config_files,
        kinds.SITE: [site_config_file],

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Prefix the key with its section, e.g. 'global.index-url' or 'install.no-index'.
2. Use 'pip config list' to see existing keys and their section prefixes.
3. Consult 'pip config --help' for the section.name format.

Example fix

# before
pip config set index-url https://pypi.org/simple
# after
pip config set global.index-url https://pypi.org/simple

def validate_config_key(key: str) -> None:
    if '.' not in key:
        raise ValueError(
            f"pip config key must be 'section.name'; got {key!r}. "
            f"Try 'global.{key}'."
        )

validate_config_key('index-url')  # raises with a helpful message

def is_sectioned_config_key(key: str) -> bool:
    """True if key has the required 'section.name' form for pip config."""
    return isinstance(key, str) and '.' in key and all(key.split('.', 1))

When it happens

Trigger: Calling pip config get/set/unset with a key that contains no dot, e.g. 'pip config set index-url https://...'. _disassemble_key is invoked from get_value (configuration.py:156), set_value (configuration.py:168), and unset_value (configuration.py:195).

Common situations: New users unfamiliar with the section.key convention; forgetting the 'global.' / 'install.' / 'user.' prefix; copying an option name directly from documentation into 'pip config set'.

Related errors

• Got invalid value for load_only - should be one of {}
• No such key - {orig_key}
• Fatal Internal error [id=1]. Please report as a bug.
• An error occurred while writing to the configuration file {f
• Needed a specific file to be modifying.

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/b02163d1282b3301.json. Report an issue: GitHub.