pypa/pip · error · InvalidSchemeCombination

Cannot set --home and --prefix together

Error message

Cannot set --home and --prefix together

What it means

InvalidSchemeCombination raised by get_scheme() when both home=<set> and prefix=<set> are passed. Like --user/--prefix, --home and --prefix are distinct, mutually exclusive installation schemes and cannot be combined; the check at line 151-152 rejects the combination immediately.

Source

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

    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}
    elif prefix is not None:
        variables = {k: prefix for k in _HOME_KEYS}

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Use only one of --home or --prefix.
2. Audit pip.conf, PIP_PREFIX / PIP_HOME env vars, and wrapper scripts for the stray option.
3. Prefer --prefix (the modern, well-supported option) over --home.
4. Run 'pip config list' to confirm no lingering combined setting.

Example fix

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

# after
pip install --prefix /opt/py somepkg

def scheme_args_ok(home, prefix) -> bool:
    return not (home and prefix)
assert scheme_args_ok(args.home, args.prefix)

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

from pip._internal.exceptions import InvalidSchemeCombination
try:
    get_scheme(name, home=h, prefix=p)
except InvalidSchemeCombination as e:
    # choose --prefix or --home
    ...

When it happens

Trigger: Calling get_scheme(dist_name, home='/h', prefix='/p') or running pip with both --home and --prefix. These are legacy distutils-style options that map to separate sysconfig schemes.

Common situations: Carrying over old distutils invocations that set --home and --prefix together; a wrapper/build script that always passes both; conflicting values inherited from pip.conf.

Related errors

• Cannot set --user 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/4f07628831f64cc5.json. Report an issue: GitHub.