pypa/pip · error · InstallationError

Can not perform a '--user' install. User site-packages are…

Error message

Can not perform a '--user' install. User site-packages are not visible in this virtualenv.

What it means

Raised by `pip install --user` inside a virtualenv that was created without global site-packages visibility. decide_user_install at install.py:798 calls virtualenv_no_global(); if the venv does not include the user site directory in its sys.path, a --user install would place files Python cannot see, so pip refuses with an InstallationError.

Solutions

  1. Drop --user inside the venv: `pip install <pkg>` installs into the venv's site-packages.
  2. If you need --user to reach a system Python, deactivate the venv first.
  3. Recreate the venv with `python -m venv --system-site-packages` if user-site visibility is genuinely required (note security/isolation trade-offs).

Example fix

// before
# inside a venv
pip install --user numpy
// after
pip install numpy
Defensive patterns

Strategy: validation

Validate before calling

# Detect a no-global venv before attempting --user install
import sys, site, os

def user_install_allowed():
    # Heuristic: in a venv, user site must be on sys.path to be visible
    if hasattr(sys, "prefix") and sys.prefix != sys.base_prefix:
        user_site = site.getusersitepackages()
        if user_site not in sys.path:
            raise EnvironmentError("--user install not visible in this venv; recreate with --system-site-packages or drop --user")
    return True

Prevention

When it happens

Trigger: Inside a virtualenv created without --system-site-packages (the default), running `pip install --user <pkg>` trips virtualenv_no_global()==True at install.py:798.

Common situations: Scripts or wrappers that always pass --user (carried over from system-Python usage), or users who habitually use --user and forget it is incompatible with isolated venvs.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/commands/install.py:799

    options.
    If use_user_site is None, the default behaviour depends on the environment,
    which is provided by the other arguments.
    """
    # In some cases (config from tox), use_user_site can be set to an integer
    # rather than a bool, which 'use_user_site is False' wouldn't catch.
    if (use_user_site is not None) and (not use_user_site):
        logger.debug("Non-user install by explicit request")
        return False

    # If we have been asked for a user install explicitly, check compatibility.
    if use_user_site:
        if prefix_path:
            raise CommandError(
                "Can not combine '--user' and '--prefix' as they imply "
                "different installation locations"
            )
        if virtualenv_no_global():
            raise InstallationError(
                "Can not perform a '--user' install. User site-packages "
                "are not visible in this virtualenv."
            )
        # Catch all remaining cases which honour the site.ENABLE_USER_SITE
        # value, such as a plain Python installation (e.g. no virtualenv).
        if not site.ENABLE_USER_SITE:
            raise InstallationError(
                "Can not perform a '--user' install. User site-packages "
                "are disabled for this Python."
            )
        logger.debug("User install by explicit request")
        return True

    # If we are here, user installs have not been explicitly requested/avoided
    assert use_user_site is None

    # user install incompatible with --prefix/--target
    if prefix_path or target_dir:

View on GitHub (pinned to f399c37189)