pypa/pip · error · ConfigurationError

Needed a specific file to be modifying.

Error message

Needed a specific file to be modifying.

What it means

Raised as ConfigurationError in Configuration._ensure_have_load_only() at configuration.py:237-239 when load_only is None and a mutating operation (set_value, unset_value, or save) is attempted. pip needs to know WHICH config file to modify, so a Configuration constructed without a load_only cannot target a file for writes.

Source

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

            ensure_dir(os.path.dirname(fname))

            # Ensure directory's permission(need to be writeable)
            try:
                with open(fname, "w") as f:
                    parser.write(f)
            except OSError as error:
                raise ConfigurationError(
                    f"An error occurred while writing to the configuration file "
                    f"{fname}: {error}"
                )

    #
    # Private routines
    #

    def _ensure_have_load_only(self) -> None:
        if self.load_only is None:
            raise ConfigurationError("Needed a specific file to be modifying.")
        logger.debug("Will be working with %s variant only", self.load_only)

    @property
    def _dictionary(self) -> dict[str, dict[str, Any]]:
        """A dictionary representing the loaded configuration."""
        # NOTE: Dictionaries are not populated if not loaded. So, conditionals
        #       are not needed here.
        retval = {}

        for variant in OVERRIDE_ORDER:
            retval.update(self._config[variant])

        return retval

    def _load_config_files(self) -> None:
        """Loads configuration from configuration files"""
        config_files = dict(self.iter_config_files())
        if config_files[kinds.ENV][0:1] == [os.devnull]:

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Construct Configuration with a concrete load_only ('user', 'global', or 'site') before calling mutating methods.
2. Use the 'pip config set/unset' CLI which always supplies the correct load_only from the --user/--global/--site flag.
3. Separate read-only usage (load_only=None is fine for reads) from write usage (load_only required).

Example fix

# before
cfg = Configuration(isolated=False)  # load_only=None
cfg.set_value('global.index-url', 'https://...')  # raises
# after
cfg = Configuration(isolated=False, load_only='user')
cfg.load()
cfg.set_value('global.index-url', 'https://...')
cfg.save()

from pip._internal.configuration import Configuration, VALID_LOAD_ONLY

def writable_config(load_only):
    if load_only is None:
        raise ValueError('load_only is required for mutating operations; pass user/global/site')
    if load_only not in VALID_LOAD_ONLY:
        raise ValueError(f'load_only must be one of {VALID_LOAD_ONLY}')
    return Configuration(isolated=False, load_only=load_only)

cfg = writable_config('user')

from pip._internal.configuration import VALID_LOAD_ONLY

def is_ready_for_writes(cfg) -> bool:
    return getattr(cfg, 'load_only', None) in VALID_LOAD_ONLY

When it happens

Trigger: Calling Configuration.set_value/unset_value/save on an instance built with load_only=None. _ensure_have_load_only is called at the top of set_value (configuration.py:162), unset_value (configuration.py:183), and save (configuration.py:215). Programmatic/internal usage that forgets to scope the Configuration to a single variant.

Common situations: Internal tooling that constructs Configuration(isolated=False) without load_only and then tries to write; misuse of pip's internal Configuration API outside the CLI's normal 'pip config set --user/--global/--site' flow.

Related errors

• Got invalid value for load_only - should be one of {}
• Key does not contain dot separated section and key. Perhaps
• 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

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