pypa/pip · error · InstallationError

Will not install to the user site because it will lack…

Error message

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

What it means

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.

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.

Example fix

# before
pip install --user requests
# after (inside venv)
pip install requests

Defensive patterns

Strategy: validation

Validate before calling

# Before invoking pip inside a venv, never pass --user.
import sys, subprocess
in_venv = hasattr(sys, "real_prefix") or (
    getattr(sys, "base_prefix", sys.prefix) != sys.prefix
)
user_flag = "--user" in sys.argv
if in_venv and user_flag:
    raise SystemExit("Refusing --user inside a virtualenv (would be shadowed)")

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/b4a96c090a3a1389. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/req/req_install.py:426

        self.should_reinstall appropriately.
        """
        if self.req is None:
            return
        existing_dist = get_default_environment().get_distribution(self.req.name)
        if not existing_dist:
            return

        version_compatible = self.req.specifier.contains(
            existing_dist.version,
            prereleases=True,
        )
        if not version_compatible:
            self.satisfied_by = None
            if use_user_site:
                if existing_dist.in_usersite:
                    self.should_reinstall = True
                elif running_under_virtualenv() and existing_dist.in_site_packages:
                    raise InstallationError(
                        f"Will not install to the user site because it will "
                        f"lack sys.path precedence to {existing_dist.raw_name} "
                        f"in {existing_dist.location}"
                    )
            else:
                self.should_reinstall = True
        else:
            if self.editable:
                self.should_reinstall = True
                # when installing editables, nothing pre-existing should ever
                # satisfy
                self.satisfied_by = None
            else:
                self.satisfied_by = existing_dist

    # Things valid for wheels
    @property
    def is_wheel(self) -> bool:

View on GitHub (pinned to f399c37189)