pypa/pip · error · ConfigurationError

Got invalid value for load_only - should be one of {}

Error message

Got invalid value for load_only - should be one of {}

What it means

Raised as ConfigurationError in Configuration.__init__ at configuration.py:105-110 when load_only is not None and not in VALID_LOAD_ONLY (USER, GLOBAL, SITE). The Configuration object accepts loading a single variant only, and any other string (typos, internal kinds like 'env' or 'env-var') is rejected at construction time.

Source

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

class Configuration:
    """Handles management of configuration.

    Provides an interface to accessing and managing configuration files.

    This class converts provides an API that takes "section.key-name" style
    keys and stores the value associated with it as "key-name" under the
    section "section".

    This allows for a clean interface wherein the both the section and the
    key-name are preserved in an easy to manage form in the configuration files
    and the data stored is also nice.
    """

    def __init__(self, isolated: bool, load_only: Kind | None = None) -> None:
        super().__init__()

        if load_only is not None and load_only not in VALID_LOAD_ONLY:
            raise ConfigurationError(
                "Got invalid value for load_only - should be one of {}".format(
                    ", ".join(map(repr, VALID_LOAD_ONLY))
                )
            )
        self.isolated = isolated
        self.load_only = load_only

        # Because we keep track of where we got the data from
        self._parsers: dict[Kind, list[tuple[str, RawConfigParser]]] = {
            variant: [] for variant in OVERRIDE_ORDER
        }
        self._config: dict[Kind, dict[str, dict[str, Any]]] = {
            variant: {} for variant in OVERRIDE_ORDER
        }
        self._modified_parsers: list[tuple[str, RawConfigParser]] = []

    def load(self) -> None:
        """Loads configuration from configuration files and environment"""

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Use one of the three valid load_only values: 'user', 'global', or 'site'.
2. Pass load_only=None if you want to load all variants.
3. Check the VALID_LOAD_ONLY tuple / kinds enum in configuration.py for the canonical strings.

Example fix

# before
from pip._internal.configuration import Configuration
cfg = Configuration(isolated=False, load_only='environment')  # invalid
# after
cfg = Configuration(isolated=False, load_only='user')

from pip._internal.configuration import VALID_LOAD_ONLY

def make_config(isolated: bool, load_only):
    if load_only is not None and load_only not in VALID_LOAD_ONLY:
        raise ValueError(f'load_only must be one of {VALID_LOAD_ONLY} or None')
    from pip._internal.configuration import Configuration
    return Configuration(isolated=isolated, load_only=load_only)

from pip._internal.configuration import VALID_LOAD_ONLY

def is_valid_load_only(value) -> bool:
    return value is None or value in VALID_LOAD_ONLY

When it happens

Trigger: Programmatically constructing Configuration(isolated=..., load_only='something') with a value outside {'user','global','site'} — e.g. load_only='env', load_only='environment', or a typo like 'userr'. The check at configuration.py:105 compares against VALID_LOAD_ONLY defined at configuration.py:46.

Common situations: Internal/tooling code that builds a Configuration directly with the wrong variant name; passing the PIP_CONFIG_FILE-based 'env' kind as load_only; typos in wrapper scripts.

Related errors

• Needed a specific file to be modifying.
• Need exactly one file to operate upon (--user, --site, --glo
• Got unexpected number of arguments, expected {n}. (example:
• Key does not contain dot separated section and key. Perhaps
• No such key - {orig_key}

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