pypa/pip · error · ConfigurationError

Needed a specific file to be modifying.

Error message

Needed a specific file to be modifying.

What it means

Raised by Configuration._ensure_have_load_only() (called by set_value, unset_value, and save) when self.load_only is None. Mutating operations require knowing which configuration layer/file to edit, so pip refuses to proceed without an explicit --user/--global/--site selection.

Solutions

1. Specify the scope: `pip config set --global global.index-url ...` or --user or --site.
2. If using the API, construct Configuration with load_only set to one of kinds.USER/GLOBAL/SITE.
3. For read-only inspection no scope is needed; only set/unset/save require it.

Example fix

# before
pip config set global.index-url https://...   # no scope
# after
pip config set --global global.index-url https://...

def require_scope_flag(scope: str | None) -> str:
    if scope not in ('--user', '--global', '--site'):
        raise ValueError('pip config set/unset requires one of --user, --global, --site')
    return scope

When it happens

Trigger: Calling `pip config set <key> <value>` without specifying --user, --global, or --site; programmatically calling set_value/unset_value/save on a Configuration constructed with load_only=None.

Common situations: Forgetting the scope flag on `pip config set`/`unset`; scripts that call the Configuration API directly without a load_only.

Related errors

• Key does not contain dot separated section and key. Perhaps…
• Got invalid value for load_only - should be one of
• No such key
• An error occurred while writing to the configuration file
• Can not perform a '--user' install. User site-packages are…

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

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