pypa/pip · error · InvalidSchemeCombination

Cannot set --home and --prefix together

Error message

Cannot set --home and --prefix together

What it means

Raised as InvalidSchemeCombination('--home','--prefix') (exceptions.py:283) from get_scheme in _sysconfig.py:151-152. The --home (home scheme) and --prefix (prefix scheme) installation layouts are mutually exclusive and both set overlapping base directories, so get_scheme rejects the combination immediately.

Solutions

1. Use either --home or --prefix, not both; pick the scheme that matches your target layout.
2. For most modern use cases, drop --home and use --prefix (or a virtualenv).
3. Review the originating command/config file for the stale flag and remove it.

Example fix

// before
pip install --home /opt/home --prefix /opt/prefix mypkg
// after
pip install --prefix /opt/prefix mypkg

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

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

When it happens

Trigger: Invoking get_scheme(dist_name, home=<non-None>, prefix=<non-None>) — i.e. `pip install --home /myhome --prefix /myprefix`.

Common situations: Combining legacy --home semantics with a modern --prefix; wrapper tooling forwarding distutils-style flags alongside pip --prefix; user misunderstanding that --home and --prefix both redefine the install base.

Related errors

• Cannot set --user and --prefix together
• User base directory is not specified
• Unknown platform: Can not change root path prefix on…
• Cannot determine archive format of
• Could not install locked package

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

Appendix: 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 f399c37189)