{"id":"a50d1a9c55f4ebc6","repo":"pypa/pip","slug":"will-not-install-to-the-user-site-because-it-will-a50d1a","errorCode":null,"errorMessage":"Will not install to the user site because it will lack sys.path precedence to {dist.raw_name} in {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/resolution/resolvelib/factory.py","lineNumber":662,"sourceCode":"        # be uninstalled, no matter it's in global or user site, because the\n        # user site installation has precedence over global.\n        if not self._use_user_site:\n            return dist\n\n        # We're installing into user site. Remove the user site installation.\n        if dist.in_usersite:\n            return dist\n\n        # We're installing into user site, but the installed incompatible\n        # package is in global site. We can't uninstall that, and would let\n        # the new user installation to \"shadow\" it. But shadowing won't work\n        # in virtual environments, so we error out.\n        if running_under_virtualenv() and dist.in_site_packages:\n            message = (\n                f\"Will not install to the user site because it will lack \"\n                f\"sys.path precedence to {dist.raw_name} in {dist.location}\"\n            )\n            raise InstallationError(message)\n        return None\n\n    def _report_requires_python_error(\n        self, causes: Sequence[ConflictCause]\n    ) -> UnsupportedPythonVersion:\n        assert causes, \"Requires-Python error reported with no cause\"\n\n        version = self._python_candidate.version\n\n        if len(causes) == 1:\n            specifier = str(causes[0].requirement.specifier)\n            message = (\n                f\"Package {causes[0].parent.name!r} requires a different \"\n                f\"Python: {version} not in {specifier!r}\"\n            )\n            return UnsupportedPythonVersion(message)\n\n        message = f\"Packages require a different Python. {version} not in:\"","sourceCodeStart":644,"sourceCodeEnd":680,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/resolution/resolvelib/factory.py#L644-L680","documentation":"InstallationError raised by PipelineFactory.get_dist_to_uninstall in the resolvelib resolver when the user requested '--user' inside a virtualenv and the currently installed incompatible distribution lives in the venv's site-packages. Uninstalling the site-packages copy is not safe from a --user install, and in a venv the user site lacks sys.path precedence over site-packages, so a user-site install would be shadowed. pip refuses instead of producing a silently broken install.","triggerScenarios":"'pip install --user --upgrade <pkg>' inside a virtualenv where <pkg> is already installed into the venv site-packages and is incompatible with the requested version. get_dist_to_uninstall finds the dist, _use_user_site is True, dist is not in usersite, and running_under_virtualenv() + dist.in_site_packages both hold.","commonSituations":"Habitual '--user' inside venvs; wrapper scripts that always pass --user; upgrading a venv-installed package with the legacy --user flag.","solutions":["Remove '--user' from the command inside a virtualenv.","Run 'pip install --upgrade <pkg>' directly so the site-packages copy is replaced.","If you need a true user-site install, leave the venv ('deactivate') first.","For a clean slate, 'pip uninstall <pkg>' then reinstall without --user."],"exampleFix":"# before (inside venv)\npip install --user --upgrade numpy\n\n# after\npip install --upgrade numpy","handlingStrategy":"validation","validationCode":"import sys\ndef user_site_safe_in_venv() -> bool:\n    in_venv = getattr(sys, 'base_prefix', sys.prefix) != sys.prefix\n    return not in_venv","typeGuard":"def is_safe_user_install() -> bool:\n    return user_site_safe_in_venv()","tryCatchPattern":"argv = sys.argv[1:]\nif '--user' in argv and not user_site_safe_in_venv():\n    argv = [a for a in argv if a != '--user']\n    print('dropped --user inside venv to avoid precedence conflict')\nrun_pip(argv)","preventionTips":["Never combine '--user' with virtualenvs.","Wrapper script: strip '--user' when VIRTUAL_ENV is set.","Train CI to install into the venv directly."],"tags":["user-site","virtualenv","resolver","sys-path","uninstall"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}