{"record":{"id":"875d2218a739d855","repo":"pypa/pip","slug":"need-exactly-one-file-to-operate-upon-user-s","errorCode":null,"errorMessage":"Need exactly one file to operate upon (--user, --site, --global) to perform.","messagePattern":"Need exactly one file to operate upon \\(--user, --site, --global\\) to perform\\.","errorType":"exception","errorClass":"PipError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/commands/configuration.py","lineNumber":172,"sourceCode":"            )\n            if value\n        ]\n\n        if not file_options:\n            if not need_value:\n                return None\n            # Default to user, unless there's a site file.\n            elif any(\n                os.path.exists(site_config_file)\n                for site_config_file in get_configuration_files()[kinds.SITE]\n            ):\n                return kinds.SITE\n            else:\n                return kinds.USER\n        elif len(file_options) == 1:\n            return file_options[0]\n\n        raise PipError(\n            \"Need exactly one file to operate upon \"\n            \"(--user, --site, --global) to perform.\"\n        )\n\n    def list_values(self, options: Values, args: list[str]) -> None:\n        self._get_n_args(args, \"list\", n=0)\n\n        for key, value in sorted(self.configuration.items()):\n            for key, value in sorted(value.items()):\n                write_output(\"%s=%r\", key, value)\n\n    def get_name(self, options: Values, args: list[str]) -> None:\n        key = self._get_n_args(args, \"get [name]\", n=1)\n        value = self.configuration.get_value(key)\n\n        write_output(\"%s\", value)\n\n    def set_name_value(self, options: Values, args: list[str]) -> None:","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/commands/configuration.py#L154-L190","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Specify exactly one of --user, --site, --global (or none for auto-detection).","Decide your target scope: per-user, per-virtualenv (site), or system-wide, and pass only that flag.","Use `pip config debug` to inspect which files are in play before choosing."],"exampleFix":"// before\npip config set --user --global global.index-url https://pypi.org/simple\n// after\npip config set --global global.index-url https://pypi.org/simple","handlingStrategy":"validation","validationCode":"# Validate file-scope flags before calling pip config\ndef config_scope_ok(user, site, glob):\n    active = sum([bool(user), bool(site), bool(glob)])\n    if active > 1:\n        raise ValueError(\"Pass at most one of --user/--site/--global\")\n    return True\n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Allow at most one of --user/--site/--global in any pip config wrapper.","Default to no scope flag and let pip auto-detect when possible."],"tags":["cli","pip-config","argument-validation","configuration","usage-error"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}