{"record":{"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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/locations/base.py#L32-L68","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before (on unsupported os.name)\npip install --root /staging mypkg\n// after (avoid --root path)\npip install --target /staging mypkg","handlingStrategy":"validation","validationCode":"// Before calling change_root, confirm the platform is supported:\nimport os\nif os.name not in ('posix', 'nt'):\n    raise SystemExit(f'change_root unsupported on os.name={os.name!r}; avoid --root')","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import InstallationError\ntry:\n    new = change_root(root, path)\nexcept InstallationError as e:\n    if 'Unknown platform' in str(e):\n        # avoid --root; use --target/--prefix instead\n        ...","preventionTips":["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."],"tags":["installation","platform","root","scheme"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}