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 {existing_dist.raw_name} in {existing_dist.location}

What it means

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.

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 d7d0d0a394)

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

Example fix

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

# after
pip install --upgrade requests

Defensive patterns

Strategy: validation

Validate before calling

import sys
def should_use_user_site_flag() -> bool:
    return not (hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix))

Type guard

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

Try / catch

if is_inside_virtualenv() and '--user' in argv:
    argv = [a for a in argv if a != '--user']
    print('dropped --user inside venv')
run_pip(argv)

Prevention

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.

When it happens

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

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

Related errors

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