pypa/pip · error · InvalidSchemeCombination

Cannot set --user and --prefix together

Error message

Cannot set --user and --prefix together

What it means

InvalidSchemeCombination raised by get_scheme() when both user=True and prefix=<set> are passed. The two installation schemes are mutually exclusive - --user installs into the per-user site, --prefix into an arbitrary prefix - so combining them is ambiguous and rejected up front.

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

Solutions

1. Decide one target: use --user OR --prefix, not both.
2. Check pip.conf / pip.ini and PIP_* env vars for stale 'user'/'prefix' settings and remove one.
3. If you need a custom install location, use --prefix alone; if you want per-user install, drop --prefix.
4. Run 'pip config list' to see where the conflicting options come from.

Example fix

# before
pip install --user --prefix /opt/py somepkg

# after (pick one)
pip install --user somepkg
# or
pip install --prefix /opt/py somepkg

def scheme_args_ok(user: bool, prefix) -> bool:
    return not (user and prefix)
# at CLI parse time:
assert scheme_args_ok(args.user, args.prefix), 'cannot combine --user and --prefix'

def valid_scheme_combo(user: bool, home, prefix) -> bool:
    return not (user and prefix) and not (home and prefix)

from pip._internal.exceptions import InvalidSchemeCombination
try:
    get_scheme(name, user=u, home=h, prefix=p)
except InvalidSchemeCombination as e:
    # prompt user to pick one scheme
    ...

When it happens

Trigger: Calling get_scheme(dist_name, user=True, prefix='/some/path') or running pip with both --user and --prefix on the command line / in config. The check at line 149-150 fires before any scheme selection.

Common situations: A pip.conf that sets both 'user = true' and a 'prefix = ...'; passing --user --prefix together on the CLI; an environment variable (PIP_USER=1) combined with a --prefix flag; a wrapper script that always adds --user.

Related errors

• Cannot set --home and --prefix together
• Cannot use '--only-dependencies' in combination with {confli
• When restricting platform and interpreter constraints using
• Can not use any platform or abi specific options unless inst
• Platform and interpreter constraints using --python-version,

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