pypa/pip · error · InstallationError

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

Error message

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

What it means

Raised as InstallationError in decide_user_install() at install.py:798-802 when use_user_site is truthy and virtualenv_no_global() returns True. A virtualenv created with --no-site-packages (or the modern default that hides the system user-site) does not expose the user site-packages directory, so a --user install would be invisible and useless.

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

Solutions

1. Drop --user and install directly into the active virtualenv (the normal, correct behavior inside a venv).
2. If you genuinely need user-site visibility, recreate the venv with --system-site-packages.
3. Remove 'user = true' from your pip.conf before working inside venvs.

Example fix

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

import sys, site
# Detect being inside a venv that hides global/user site
in_venv = sys.prefix != sys.base_prefix
if in_venv and '--user' in sys.argv:
    # virtualenv_no_global checks pyvenv.cfg; approximate by site.ENABLE_USER_SITE
    print('WARNING: --user is not visible inside this venv; dropping --user', file=sys.stderr)
    sys.argv = [a for a in sys.argv if a != '--user']

When it happens

Trigger: Running 'pip install --user <pkg>' inside a virtualenv whose configuration hides the global/user site directory. virtualenv_no_global() checks pyvenv.cfg for include-system-site-packages=false combined with the interpreter being a venv.

Common situations: Habit of adding --user everywhere, carried into an activated venv; automation that blindly passes --user; upgrading pip itself with --user inside a venv.

Related errors

• Can not perform a '--user' install. User site-packages are d
• Will not install to the user site because it will lack sys.p
• No module named {module!r}
• Can not combine '--user' and '--target'
• Target path exists but is not a directory, will not continue

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