{"record":{"id":"b4a96c090a3a1389","repo":"pypa/pip","slug":"will-not-install-to-the-user-site-because-it-will","errorCode":null,"errorMessage":"Will not install to the user site because it will lack sys.path precedence to {existing_dist.raw_name} in {existing_dist.location}","messagePattern":"Will not install to the user site because it will lack sys\\.path precedence to (.+?) in (.+?)","errorType":"exception","errorClass":"InstallationError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/req/req_install.py","lineNumber":426,"sourceCode":"        self.should_reinstall appropriately.\n        \"\"\"\n        if self.req is None:\n            return\n        existing_dist = get_default_environment().get_distribution(self.req.name)\n        if not existing_dist:\n            return\n\n        version_compatible = self.req.specifier.contains(\n            existing_dist.version,\n            prereleases=True,\n        )\n        if not version_compatible:\n            self.satisfied_by = None\n            if use_user_site:\n                if existing_dist.in_usersite:\n                    self.should_reinstall = True\n                elif running_under_virtualenv() and existing_dist.in_site_packages:\n                    raise InstallationError(\n                        f\"Will not install to the user site because it will \"\n                        f\"lack sys.path precedence to {existing_dist.raw_name} \"\n                        f\"in {existing_dist.location}\"\n                    )\n            else:\n                self.should_reinstall = True\n        else:\n            if self.editable:\n                self.should_reinstall = True\n                # when installing editables, nothing pre-existing should ever\n                # satisfy\n                self.satisfied_by = None\n            else:\n                self.satisfied_by = existing_dist\n\n    # Things valid for wheels\n    @property\n    def is_wheel(self) -> bool:","sourceCodeStart":408,"sourceCodeEnd":444,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/req/req_install.py#L408-L444","documentation":"Raised by check_if_exists (req_install.py:426) when pip is told to install with --user while running inside a virtualenv, and an incompatible version of the same package already lives in the venv's site-packages. Because venv site-packages precedes the user site on sys.path, the --user install would be silently shadowed, so pip refuses rather than install something unusable. Only triggered when running_under_virtualenv() and existing_dist.in_site_packages and use_user_site are all true.","triggerScenarios":"Running `pip install --user <pkg>` (or any flow setting use_user_site) inside an active virtualenv where <pkg> is already installed in the venv site-packages at an incompatible version.","commonSituations":"Habitual `--user` flag carried over from system-Python workflows into a venv; wrapper scripts that always pass --user; CI that activates a venv but keeps --user flags.","solutions":["Drop the --user flag when inside a virtualenv (venv site-packages is already isolated).","Uninstall the existing venv copy first, then reinstall without --user.","Reinstall with pip install --force-reinstall <pkg> inside the venv to replace the incompatible version."],"exampleFix":"# before\npip install --user requests\n# after (inside venv)\npip install requests","handlingStrategy":"validation","validationCode":"# Before invoking pip inside a venv, never pass --user.\nimport sys, subprocess\nin_venv = hasattr(sys, \"real_prefix\") or (\n    getattr(sys, \"base_prefix\", sys.prefix) != sys.prefix\n)\nuser_flag = \"--user\" in sys.argv\nif in_venv and user_flag:\n    raise SystemExit(\"Refusing --user inside a virtualenv (would be shadowed)\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine --user with an active virtualenv.","Detect venv activation in wrapper scripts and strip --user before calling pip.","Document that venvs already isolate site-packages, making --user redundant."],"tags":["user-site","virtualenv","sys-path"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}