pypa/pip · error · PipError

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

Error message

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

What it means

Raised by ConfigurationCommand._determine_file when more than one of --user, --global, --site is selected. pip needs a single target config file to read or modify, so two or more file-scope flags are ambiguous and rejected at configuration.py:172. (Zero flags is fine and resolves to site or user.)

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 d7d0d0a394)

Solutions

1. Pass exactly one of --user, --global, or --site.
2. Decide the intended scope first: user = per-user file, global = system-wide, site = current venv.
3. If you need to inspect all scopes, use 'pip config debug' with no scope flag.

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

scopes = {"--user": user, "--global": global_, "--site": site}
selected = [k for k, v in scopes.items() if v]
if len(selected) > 1:
    raise SystemExit(f"Pass exactly one scope; got {selected}")

When it happens

Trigger: Running e.g. 'pip config set --user --global global.index-url ...' or combining any two of the three file-scope flags on get/set/unset/edit/list/debug.

Common situations: Copy-pasting a config snippet that already had --user and adding --global; wrapper scripts that always pass --user and let the user add more; misunderstandings about precedence.

Related errors

• Got unexpected number of arguments, expected {n}. (example:
• --require-hashes and --no-require-hashes are mutually exclus
• Too many arguments
• Could not determine appropriate file.
• Can not open an editor for a file name containing " {fname}

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