pypa/pip · error · PipError

Need exactly one file to operate upon (--user, --site…

Error message

Need exactly one file to operate upon (--user, --site, --global) to perform.

What it means

Raised by `pip config` when more than one of --user, --site, --global is specified simultaneously. _determine_file at configuration.py:147 collects the active file-option flags; if more than one is True, pip cannot decide which config file to modify. This is a PipError caught in ConfigurationCommand.run.

Solutions

1. Specify exactly one of --user, --site, --global (or none for auto-detection).
2. Decide your target scope: per-user, per-virtualenv (site), or system-wide, and pass only that flag.
3. Use `pip config debug` to inspect which files are in play before choosing.

Example fix

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

# Validate file-scope flags before calling pip config
def config_scope_ok(user, site, glob):
    active = sum([bool(user), bool(site), bool(glob)])
    if active > 1:
        raise ValueError("Pass at most one of --user/--site/--global")
    return True

When it happens

Trigger: Invoking e.g. `pip config set --user --global global.index-url <url>` — the file_options list has length > 1, falling through all branches to the raise at configuration.py:172.

Common situations: User copy-pastes options from different recipes, or scripts combine flags assuming pip will pick a precedence. Also seen when migrating from --user to --site and forgetting to remove the old flag.

Related errors

• Got unexpected number of arguments, expected
• Can not combine '--user' and '--prefix' as they imply…
• Can not combine '--user' and '--target'
• Could not determine appropriate file.
• Could not determine editor to use.

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

Appendix: source

Thrown at src/pip/_internal/commands/configuration.py:172

            )
            if value
        ]

        if not file_options:
            if not need_value:
                return None
            # Default to user, unless there's a site file.
            elif any(
                os.path.exists(site_config_file)
                for site_config_file in get_configuration_files()[kinds.SITE]
            ):
                return kinds.SITE
            else:
                return kinds.USER
        elif len(file_options) == 1:
            return file_options[0]

        raise PipError(
            "Need exactly one file to operate upon "
            "(--user, --site, --global) to perform."
        )

    def list_values(self, options: Values, args: list[str]) -> None:
        self._get_n_args(args, "list", n=0)

        for key, value in sorted(self.configuration.items()):
            for key, value in sorted(value.items()):
                write_output("%s=%r", key, value)

    def get_name(self, options: Values, args: list[str]) -> None:
        key = self._get_n_args(args, "get [name]", n=1)
        value = self.configuration.get_value(key)

        write_output("%s", value)

    def set_name_value(self, options: Values, args: list[str]) -> None:

View on GitHub (pinned to f399c37189)