{"record":{"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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/resolution/resolvelib/factory.py#L644-L680","documentation":"Raised as InstallationError when pip is asked to install a package into the user site (via --user) inside a virtualenv, but a conflicting version of that package is already installed in the virtualenv's site-packages. In a virtualenv, the user site directory does not have sys.path precedence over site-packages, so the new user-site install would be shadowed by the old global install and silently fail to take effect. Rather than produce a broken install, pip refuses to proceed.","triggerScenarios":"Running `pip install --user <pkg>` inside an active virtualenv where <pkg> is already present in the virtualenv's site-packages. The factory.get_dist_to_uninstall() method (factory.py:637) detects _use_user_site=True, dist.in_usersite=False, running_under_virtualenv()=True, and dist.in_site_packages=True, triggering the raise at line 662.","commonSituations":"Forgetting to activate the correct virtualenv before running pip install --user. Copying install commands (that include --user) from system-Python tutorials into a virtualenv workflow. Migrating from system pip to venv-based pip and reusing --user flags out of habit.","solutions":["Remove the --user flag: inside a virtualenv, packages already install into the venv's site-packages, so --user is unnecessary and counterproductive.","If you truly want a user-site install, exit the virtualenv (deactivate) first, then run the --user install against the system interpreter.","Uninstall the existing copy from site-packages first (`pip uninstall <pkg>`), then reinstall without --user.","Recreate or repair the virtualenv if site-packages is in an inconsistent state."],"exampleFix":"// before\n(venv) $ pip install --user requests\n\n// after\n(venv) $ pip install requests","handlingStrategy":"validation","validationCode":"import sys, site\n\n# Before running pip install --user, check if in a venv\nvenv = hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix)\nif venv:\n    print('Inside a virtualenv: do NOT pass --user (it lacks path precedence).')\n    # omit --user from your pip command\nelse:\n    print('System Python: --user is acceptable.')","typeGuard":"import sys\n\ndef should_use_user_flag() -> bool:\n    \"\"\"Returns True only if --user is safe (not inside a venv).\"\"\"\n    in_venv = hasattr(sys, 'real_prefix') or sys.base_prefix != sys.prefix\n    return not in_venv","tryCatchPattern":null,"preventionTips":["Never use --user inside an activated virtualenv; the venv already isolates packages.","Centralise pip invocation in a wrapper that drops --user when VIRTUAL_ENV is set.","Document in your project README that installs target the active venv, not the user site."],"tags":["installation","virtualenv","user-site","path-precedence"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}