{"id":"321873962833d89b","repo":"pypa/pip","slug":"unknown-platform-os-name-can-not-change-root-pa","errorCode":null,"errorMessage":"Unknown platform: {os.name}\nCan not change root path prefix on unknown platform.","messagePattern":"Unknown platform: (.+?)\nCan not change root path prefix on unknown platform\\.","errorType":"exception","errorClass":"InstallationError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/locations/base.py","lineNumber":50,"sourceCode":"    Otherwise, it requires making 'pathname' relative and then joining the\n    two, which is tricky on DOS/Windows and Mac OS.\n\n    This is borrowed from Python's standard library's distutils module.\n    \"\"\"\n    if os.name == \"posix\":\n        if not os.path.isabs(pathname):\n            return os.path.join(new_root, pathname)\n        else:\n            return os.path.join(new_root, pathname[1:])\n\n    elif os.name == \"nt\":\n        drive, path = os.path.splitdrive(pathname)\n        if path[0] == \"\\\\\":\n            path = path[1:]\n        return os.path.join(new_root, path)\n\n    else:\n        raise InstallationError(\n            f\"Unknown platform: {os.name}\\n\"\n            \"Can not change root path prefix on unknown platform.\"\n        )\n\n\ndef get_src_prefix() -> str:\n    if running_under_virtualenv():\n        src_prefix = os.path.join(sys.prefix, \"src\")\n    else:\n        # FIXME: keep src in cwd for now (it is not a temporary folder)\n        try:\n            src_prefix = os.path.join(os.getcwd(), \"src\")\n        except OSError:\n            # In case the current working directory has been renamed or deleted\n            sys.exit(\"The folder you are executing pip from can no longer be found.\")\n\n    # under macOS + virtualenv sys.prefix is not properly resolved\n    # it is something like /path/to/python/bin/..","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/locations/base.py#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"# before - test patches os.name to ''\nmonkeypatch.setattr(os, 'name', '')\nchange_root('/fakeroot', '/usr/lib/x')\n\n# after\nmonkeypatch.setattr(os, 'name', 'posix')\nchange_root('/fakeroot', '/usr/lib/x')","handlingStrategy":"validation","validationCode":"import os\nif os.name not in ('posix', 'nt'):\n    raise SystemExit(f'change_root unsupported on os.name={os.name!r}; use a supported platform or drop --root')","typeGuard":"def change_root_supported() -> bool:\n    import os\n    return os.name in ('posix', 'nt')","tryCatchPattern":"from pip._internal.exceptions import InstallationError\ntry:\n    change_root(new_root, path)\nexcept InstallationError as e:\n    if 'Unknown platform' in str(e):\n        # fall back to no --root, or pick a supported platform\n        ...","preventionTips":["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."],"tags":["install-location","platform","root","unsupported-os"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}