{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/req/req_install.py#L408-L444","documentation":"InstallationError raised by InstallRequirement.check_if_exists during the legacy/new install path when the user asked for a --user install inside a virtualenv, an incompatible version of the package is already installed in the venv's site-packages, and the installed copy is not in the user site. Installing to --user would shadow-but-not-override the site-packages copy because in a venv the user site does not have sys.path precedence over site-packages. pip refuses rather than produce a broken install.","triggerScenarios":"'pip install --user --upgrade <pkg>' inside an active virtualenv where <pkg> is already installed in the venv's site-packages at an incompatible version. The version-compatibility check fails, use_user_site is True, the venv branch is taken, and the dist is in_site_packages.","commonSituations":"Muscle-memory '--user' flag carried over from system-Python habits now used inside a venv; tooling wrapper that always passes --user; upgrading a package that was venv-installed.","solutions":["Drop '--user' when inside a virtualenv — venvs already isolate packages, so --user is unnecessary and harmful.","If you truly need to replace the package, run 'pip install --upgrade <pkg>' (no --user).","To force reinstallation use 'pip install --force-reinstall <pkg>'.","Exit the venv first if you genuinely want a user-site install: 'deactivate' then 'pip install --user <pkg>'."],"exampleFix":"# before (inside venv)\npip install --user --upgrade requests\n\n# after\npip install --upgrade requests","handlingStrategy":"validation","validationCode":"import sys\ndef should_use_user_site_flag() -> bool:\n    return not (hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix))","typeGuard":"def is_inside_virtualenv() -> bool:\n    import sys\n    return getattr(sys, 'base_prefix', sys.prefix) != sys.prefix","tryCatchPattern":"if is_inside_virtualenv() and '--user' in argv:\n    argv = [a for a in argv if a != '--user']\n    print('dropped --user inside venv')\nrun_pip(argv)","preventionTips":["Do not pass '--user' inside virtualenvs.","Wrap pip in a script that strips '--user' when VIRTUAL_ENV is set.","Teach CI to drop '--user' once a venv is activated."],"tags":["user-site","virtualenv","install","sys-path"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}