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 by Configuration.__init__ when the load_only argument is not None and is not one of the three valid kinds: 'user', 'global', or 'site'. load_only restricts which configuration layer pip reads/writes, so an unrecognized value would make behavior undefined. This is an internal/programmatic error — the CLI maps --user/--global/--site to these strings, so end users rarely see it directly.

Solutions

  1. Pass one of the valid load_only values: 'user', 'global', or 'site' (the pip._internal.configuration.kinds constants).
  2. If you do not need to restrict to a single layer, pass load_only=None.
  3. If calling via the CLI, use --user / --global / --site which map correctly internally.

Example fix

# before
from pip._internal.configuration import Configuration
cfg = Configuration(isolated=False, load_only='env')
# after
from pip._internal.configuration import Configuration, kinds
cfg = Configuration(isolated=False, load_only=kinds.GLOBAL)
Defensive patterns

Strategy: validation

Validate before calling

VALID_LOAD_ONLY = {'user', 'global', 'site'}

def make_configuration(isolated: bool, load_only: str | None):
    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, got {load_only!r}')
    from pip._internal.configuration import Configuration
    return Configuration(isolated=isolated, load_only=load_only)

Type guard

def is_valid_load_only(value: str | None) -> bool:
    return value is None or value in {'user', 'global', 'site'}

Prevention

When it happens

Trigger: Instantiating Configuration(isolated=False, load_only='something') directly with an invalid string; a bug or monkey-patch that passes an unexpected load_only value; a typo in code that wraps pip's configuration layer.

Common situations: Third-party tools that embed pip and construct a Configuration object with a wrong constant; test harnesses passing arbitrary strings; version skew where a vendored enum value changed.

Related errors

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

Appendix: 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 f399c37189)