pypa/pip · error · InstallationError

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

Error message

Can not perform a '--user' install. User site-packages are disabled for this Python.

What it means

Raised as InstallationError in decide_user_install() at install.py:805-809 when use_user_site is truthy and site.ENABLE_USER_SITE is False. The running Python was built or configured to disable the user site-packages directory entirely (e.g. python started with -s or PYTHONNOUSERSITE set), so a --user install cannot place files anywhere visible.

Source

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

        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:
        logger.debug("Non-user install due to --prefix or --target option")
        return False

    # If user installs are not enabled, choose a non-user install
    if not site.ENABLE_USER_SITE:
        logger.debug("Non-user install because user site-packages disabled")
        return False

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Remove --user and install to the system or virtualenv site-packages (use a venv or --break-system-packages / --target if needed).
2. Unset PYTHONNOUSERSITE and avoid launching python with -s, then retry --user.
3. Install into a virtualenv instead, which sidesteps the user-site flag entirely.

Example fix

# before
$ export PYTHONNOUSERSITE=1
$ pip install --user requests  # fails
# after
$ unset PYTHONNOUSERSITE
$ pip install --user requests

import os, site, sys
if os.environ.get('PYTHONNOUSERSITE') or not site.ENABLE_USER_SITE:
    if '--user' in sys.argv:
        print('ERROR: user-site is disabled in this interpreter; cannot use --user', file=sys.stderr)
        sys.exit(2)

When it happens

Trigger: The interpreter has user-site disabled — PYTHONNOUSERSITE=1 in the environment, python invoked with -s, or a distro build of Python that defaults site.ENABLE_USER_SITE to False. Combine that with an explicit --user install.

Common situations: Distro-managed Python (some RHEL/Debian setups), container images that export PYTHONNOUSERSITE, or wrapper scripts that add -s. The user copies a --user command from a tutorial without realizing their interpreter forbids user-site.

Related errors

• Can not perform a '--user' install. User site-packages are n
• Could not determine appropriate file.
• Editor Subprocess exited with exit code {e.returncode}
• No module named {module!r}
• Can not combine '--user' and '--target'

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