pypa/pip · error · InstallationError

Unknown platform: {os.name} Can not change root path prefix

Error message

Unknown platform: {os.name}
Can not change root path prefix on unknown platform.

What it means

InstallationError raised by change_root() when os.name is neither 'posix' nor 'nt'. The function re-bases an absolute install path under a new root (for --root / install_root) using platform-specific drive/stripping logic; an unknown OS means it cannot safely compute the rewritten path.

Source

Thrown at src/pip/_internal/locations/base.py:50

    Otherwise, it requires making 'pathname' relative and then joining the
    two, which is tricky on DOS/Windows and Mac OS.

    This is borrowed from Python's standard library's distutils module.
    """
    if os.name == "posix":
        if not os.path.isabs(pathname):
            return os.path.join(new_root, pathname)
        else:
            return os.path.join(new_root, pathname[1:])

    elif os.name == "nt":
        drive, path = os.path.splitdrive(pathname)
        if path[0] == "\\":
            path = path[1:]
        return os.path.join(new_root, path)

    else:
        raise InstallationError(
            f"Unknown platform: {os.name}\n"
            "Can not change root path prefix on unknown platform."
        )


def get_src_prefix() -> str:
    if running_under_virtualenv():
        src_prefix = os.path.join(sys.prefix, "src")
    else:
        # FIXME: keep src in cwd for now (it is not a temporary folder)
        try:
            src_prefix = os.path.join(os.getcwd(), "src")
        except OSError:
            # In case the current working directory has been renamed or deleted
            sys.exit("The folder you are executing pip from can no longer be found.")

    # under macOS + virtualenv sys.prefix is not properly resolved
    # it is something like /path/to/python/bin/..

View on GitHub (pinned to d7d0d0a394)

Solutions

Run pip on a supported platform (posix/nt) where change_root has defined behavior.
Drop --root / --install-option root if you do not need path re-basing.
If porting Python/pip to a new OS, add a branch for your os.name in change_root upstream.
In tests, patch os.name to 'posix' or 'nt' rather than a sentinel value.

Example fix

# before - test patches os.name to ''
monkeypatch.setattr(os, 'name', '')
change_root('/fakeroot', '/usr/lib/x')

# after
monkeypatch.setattr(os, 'name', 'posix')
change_root('/fakeroot', '/usr/lib/x')

Defensive patterns

Strategy: validation

Validate before calling

import os
if os.name not in ('posix', 'nt'):
    raise SystemExit(f'change_root unsupported on os.name={os.name!r}; use a supported platform or drop --root')

Type guard

def change_root_supported() -> bool:
    import os
    return os.name in ('posix', 'nt')

Try / catch

from pip._internal.exceptions import InstallationError
try:
    change_root(new_root, path)
except InstallationError as e:
    if 'Unknown platform' in str(e):
        # fall back to no --root, or pick a supported platform
        ...

Prevention

Run pip on posix/nt platforms for --root support.
In tests, patch os.name to 'posix' or 'nt'.
Drop --root if path re-basing is unnecessary.
When porting, extend change_root for the new os.name upstream.

When it happens

Trigger: Calling change_root(new_root, pathname) on a platform where os.name is something other than 'posix' or 'nt' (e.g. an experimental/legacy port, or a mocked environment where os.name was patched). Reached when pip applies --root during installation.

Common situations: Running pip on an unsupported/emulated platform; a test that monkeypatches os.name to an unexpected value while exercising install --root; a custom Python build on an exotic OS (some BSD variants report 'posix', so this is rare).

Related errors

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