What causes "Cannot set --user and --prefix together" in pypa/pip?

Pick one target: use --user for per-user installs, or --prefix for a custom prefix location.

pypa/pip · error · InvalidSchemeCombination

Cannot set --user and --prefix together

Error message

Cannot set --user and --prefix together

What it means

Raised as InvalidSchemeCombination('--user','--prefix') (exceptions.py:283, str yields 'Cannot set --user and --prefix together') from get_scheme in _sysconfig.py:149-150. The two install schemes are mutually exclusive: --user installs into the per-user site, while --prefix installs into an arbitrary prefix, so passing both is ambiguous and rejected before any path is computed.

Solutions

Pick one target: use --user for per-user installs, or --prefix for a custom prefix location.
If installing into a virtualenv-style layout, prefer creating a venv and dropping both flags.
Audit wrapper scripts/CI for flags that conflict before forwarding them to pip.

Example fix

// before
pip install --user --prefix /opt/mypkg mypkg
// after (choose one)
pip install --prefix /opt/mypkg mypkg

Defensive patterns

Strategy: validation

Validate before calling

// Reject conflicting flags before calling get_scheme / pip:
if user and prefix:
    raise SystemExit('--user and --prefix are mutually exclusive')

Try / catch

from pip._internal.exceptions import InvalidSchemeCombination
try:
    scheme = get_scheme(dist, user=user, prefix=prefix)
except InvalidSchemeCombination:
    # drop one of the conflicting flags
    ...

Prevention

Never combine --user with --prefix.
Validate install-target flags in wrapper scripts before forwarding to pip.
Document a single canonical install-location strategy in CI templates.

When it happens

Trigger: Invoking get_scheme(dist_name, user=True, prefix=<non-None>) — i.e. combining `pip install --user --prefix /some/path`.

Common situations: Copy-pasting flags from two different install recipes; a wrapper script or CI matrix that always passes --user but also injects --prefix; misconfigured build tooling that forwards both.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/locations/_sysconfig.py:150

    root: str | None = None,
    isolated: bool = False,
    prefix: str | None = None,
) -> Scheme:
    """
    Get the "scheme" corresponding to the input parameters.

    :param dist_name: the name of the package to retrieve the scheme for, used
        in the headers scheme path
    :param user: indicates to use the "user" scheme
    :param home: indicates to use the "home" scheme
    :param root: root under which other directories are re-based
    :param isolated: ignored, but kept for distutils compatibility (where
        this controls whether the user-site pydistutils.cfg is honored)
    :param prefix: indicates to use the "prefix" scheme and provides the
        base directory for the same
    """
    if user and prefix:
        raise InvalidSchemeCombination("--user", "--prefix")
    if home and prefix:
        raise InvalidSchemeCombination("--home", "--prefix")

    if home is not None:
        scheme_name = _infer_home()
    elif user:
        scheme_name = _infer_user()
    else:
        scheme_name = _infer_prefix()

    # Special case: When installing into a custom prefix, use posix_prefix
    # instead of osx_framework_library. See _should_use_osx_framework_prefix()
    # docstring for details.
    if prefix is not None and scheme_name == "osx_framework_library":
        scheme_name = "posix_prefix"

    if home is not None:
        variables = {k: home for k in _HOME_KEYS}

View on GitHub (pinned to f399c37189)