pypa/pip · error · CommandError

Can not combine '--user' and '--prefix' as they imply…

Error message

Can not combine '--user' and '--prefix' as they imply different installation locations

What it means

Raised by `pip install` when both --user and --prefix are supplied. decide_user_install at install.py:793 raises CommandError because --user installs to the user site-packages (~/.local) while --prefix installs to an arbitrary prefix's lib — the two locations conflict and cannot be honored together.

Solutions

Choose one: drop --user (use --prefix alone) or drop --prefix (use --user alone).
For a relocatable install under a prefix use `pip install --prefix /opt/mypython <pkg>`.
For per-user install use `pip install --user <pkg>`.

Example fix

// before
pip install --user --prefix /opt/mypython numpy
// after
pip install --prefix /opt/mypython numpy

Defensive patterns

Strategy: validation

Validate before calling

# Reject combining --user and --prefix before invoking pip install
def install_opts_ok(use_user, prefix_path):
    if use_user and prefix_path is not None:
        raise ValueError("--user and --prefix are mutually exclusive")
    return True

Prevention

Never pass both --user and --prefix in the same invocation.
Decide between user-site and prefix-based installs up front.

When it happens

Trigger: Invoking `pip install --user --prefix /opt/mypython <pkg>` — use_user_site is truthy and prefix_path is set, hitting install.py:793-797. Note this check is only reached when --user is explicitly requested (truthy).

Common situations: User combines flags assuming pip will prefer one, or migrates between user installs and prefix installs without removing the old flag.

Related errors

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

Appendix: source

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

) -> bool:
    """Determine whether to do a user install based on the input options.

    If use_user_site is False, no additional checks are done.
    If use_user_site is True, it is checked for compatibility with other
    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

View on GitHub (pinned to f399c37189)