pypa/pip · error · InstallationError

Will not install to the user site because it will lack sys.p

Error message

Will not install to the user site because it will lack sys.path precedence to {dist.raw_name} in {dist.location}

What it means

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.

Source

Thrown at src/pip/_internal/resolution/resolvelib/factory.py:662

        # be uninstalled, no matter it's in global or user site, because the
        # user site installation has precedence over global.
        if not self._use_user_site:
            return dist

        # We're installing into user site. Remove the user site installation.
        if dist.in_usersite:
            return dist

        # We're installing into user site, but the installed incompatible
        # package is in global site. We can't uninstall that, and would let
        # the new user installation to "shadow" it. But shadowing won't work
        # in virtual environments, so we error out.
        if running_under_virtualenv() and dist.in_site_packages:
            message = (
                f"Will not install to the user site because it will lack "
                f"sys.path precedence to {dist.raw_name} in {dist.location}"
            )
            raise InstallationError(message)
        return None

    def _report_requires_python_error(
        self, causes: Sequence[ConflictCause]
    ) -> UnsupportedPythonVersion:
        assert causes, "Requires-Python error reported with no cause"

        version = self._python_candidate.version

        if len(causes) == 1:
            specifier = str(causes[0].requirement.specifier)
            message = (
                f"Package {causes[0].parent.name!r} requires a different "
                f"Python: {version} not in {specifier!r}"
            )
            return UnsupportedPythonVersion(message)

        message = f"Packages require a different Python. {version} not in:"

View on GitHub (pinned to d7d0d0a394)

Solutions

  1. Remove '--user' from the command inside a virtualenv.
  2. Run 'pip install --upgrade <pkg>' directly so the site-packages copy is replaced.
  3. If you need a true user-site install, leave the venv ('deactivate') first.
  4. For a clean slate, 'pip uninstall <pkg>' then reinstall without --user.

Example fix

# before (inside venv)
pip install --user --upgrade numpy

# after
pip install --upgrade numpy
Defensive patterns

Strategy: validation

Validate before calling

import sys
def user_site_safe_in_venv() -> bool:
    in_venv = getattr(sys, 'base_prefix', sys.prefix) != sys.prefix
    return not in_venv

Type guard

def is_safe_user_install() -> bool:
    return user_site_safe_in_venv()

Try / catch

argv = sys.argv[1:]
if '--user' in argv and not user_site_safe_in_venv():
    argv = [a for a in argv if a != '--user']
    print('dropped --user inside venv to avoid precedence conflict')
run_pip(argv)

Prevention

When it happens

Trigger: '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.

Common situations: Habitual '--user' inside venvs; wrapper scripts that always pass --user; upgrading a venv-installed package with the legacy --user flag.

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/a50d1a9c55f4ebc6.json. Report an issue: GitHub.