pypa/pip · error · CommandError

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

Error message

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

What it means

Raised in decide_user_install() at install.py:793-797 as a CommandError when use_user_site is truthy and a --prefix path is also supplied. --user writes to the user site-packages directory while --prefix writes to an alternate prefix layout (lib/, bin/, etc.); the two imply completely different install locations so pip refuses the combination.

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

Solutions

1. Remove either --user or --prefix from the command.
2. If you want a prefix-style layout, drop --user and keep --prefix <dir>.
3. If you want a user-site install, drop --prefix and keep --user.
4. Audit pip.conf for a 'user = true' line that silently conflicts with your --prefix flag.

Example fix

# before
pip install --user --prefix /opt/mypkg requests
# after
pip install --prefix /opt/mypkg requests

import sys

user_flag = '--user' in sys.argv
prefix_flag = any(a in ('--prefix',) or a.startswith('--prefix=') for a in sys.argv)
if user_flag and prefix_flag:
    print('ERROR: --user and --prefix are mutually exclusive', file=sys.stderr)
    sys.exit(2)

When it happens

Trigger: Passing both --user and --prefix on the same pip install command, or having 'user = true' in a config file while passing --prefix on the CLI. The check fires inside decide_user_install (install.py:792-797).

Common situations: Packaging scripts that default to --user for non-root installs while a --prefix is layered in for a staging prefix; users mistaking --prefix for --target.

Related errors

• Can not combine '--user' and '--target'
• No module named {module!r}
• Target path exists but is not a directory, will not continue
• failed-wheel-build-for-install
• Can not perform a '--user' install. User site-packages are n

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