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 disabled for this Python.

What it means

Raised by pip's decide_user_install() when the user explicitly passes --user but Python's site.ENABLE_USER_SITE flag is False, meaning the per-user site-packages directory is disabled for this interpreter. This is distinct from the virtualenv case (which is caught one branch earlier); it fires for a plain Python whose site customization, -s flag, or PYTHONNOUSERSITE environment variable has turned user installs off. The install is aborted because pip cannot honor --user when the interpreter refuses to use the user site directory.

Solutions

1. Drop the --user flag and install into a virtualenv instead: `python -m venv .venv && .venv/bin/pip install <pkg>`.
2. Unset PYTHONNOUSERSITE (`unset PYTHONNOUSERSITE`) and ensure the interpreter is not started with -s, then retry --user.
3. Install into the system site-packages with appropriate permissions (e.g. `sudo pip install` or, better, use a venv) if --user is not required.
4. If a wrapper tool forces --user, configure it to use --prefix or a target directory instead.

Example fix

# before
PYTHONNOUSERSITE=1 pip install --user requests
# after
unset PYTHONNOUSERSITE
pip install --user requests
# or, preferred:
python -m venv .venv && .venv/bin/pip install requests

import site, sys

# Run before invoking pip with --user
if not site.ENABLE_USER_SITE or sys.flags.no_user_site:
    raise SystemExit('User site-packages disabled; use a venv instead of --user')

When it happens

Trigger: Running `pip install --user <pkg>` when PYTHONNOUSERSITE is set to a truthy value, or the Python process was started with the `-s` (no user site) interpreter flag, or a custom sitecustomize.py sets ENABLE_USER_SITE=False. Also triggered by tools that hardcode `--user` (e.g. certain tox/Jupyter configs) inside containers or system Pythons that ship with user site disabled.

Common situations: System-packaged Python on Linux distributions that disable user site by default; CI containers where PYTHONNOUSERSITE is exported; running python -s -m pip install --user; Jupyter %pip magic in an environment where the kernel was launched with -s.

Related errors

• Can not perform a '--user' install. User site-packages are…
• Could not determine appropriate file.
• Could not determine editor to use.
• [dependency-groups] data was invalid in
• [dependency-groups] table was malformed in

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

Appendix: 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 f399c37189)