{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/commands/configuration.py#L154-L190","documentation":"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.)","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass exactly one of --user, --global, or --site.","Decide the intended scope first: user = per-user file, global = system-wide, site = current venv.","If you need to inspect all scopes, use 'pip config debug' with no scope flag."],"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":"scopes = {\"--user\": user, \"--global\": global_, \"--site\": site}\nselected = [k for k, v in scopes.items() if v]\nif len(selected) > 1:\n    raise SystemExit(f\"Pass exactly one scope; got {selected}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Decide scope before constructing the command.","Use 'pip config debug' (no scope) to view all scopes at once."],"tags":["pip","config","cli","configuration-conflict","invalid-argument"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}