pypa/pip · error · InstallationError

Unknown platform: Can not change root path prefix on…

Error message

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

What it means

Raised by change_root in locations/base.py:50 when os.name is neither 'posix' nor 'nt'. change_root reimplements distutils' path-rebasing logic for POSIX and Windows only; any other platform value is treated as unsupported because the drive/separator handling required to make an absolute path relative to a new root is platform-specific and not implemented.

Solutions

Run on a supported platform (POSIX or Windows) where os.name is 'posix' or 'nt'.
If installing into a relocatable layout, avoid --root and use --prefix/--target instead, which don't call change_root.
Report the platform to pip maintainers if it is a legitimate supported target.

Example fix

// before (on unsupported os.name)
pip install --root /staging mypkg
// after (avoid --root path)
pip install --target /staging mypkg

Defensive patterns

Strategy: validation

Validate before calling

// Before calling change_root, confirm the platform is supported:
import os
if os.name not in ('posix', 'nt'):
    raise SystemExit(f'change_root unsupported on os.name={os.name!r}; avoid --root')

Try / catch

from pip._internal.exceptions import InstallationError
try:
    new = change_root(root, path)
except InstallationError as e:
    if 'Unknown platform' in str(e):
        # avoid --root; use --target/--prefix instead
        ...

Prevention

Avoid --root on non-posix/non-nt platforms; use --target.
Gate platform-specific install logic on os.name.
Document supported platforms for any packaging tooling that calls change_root.

When it happens

Trigger: Calling change_root(new_root, pathname) on an interpreter whose os.name is not 'posix' or 'nt' (the function explicitly handles only those two branches and raises InstallationError in the else).

Common situations: Running pip's install machinery under an exotic/emulated platform or a Python build with an unusual os.name; very rare in practice since CPython on supported OSes reports posix or nt.

Related errors

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

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