{"id":"8827ea49244d3938","repo":"pypa/pip","slug":"user-base-directory-is-not-specified","errorCode":null,"errorMessage":"User base directory is not specified","messagePattern":"User base directory is not specified","errorType":"exception","errorClass":"UserInstallationInvalid","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/locations/_sysconfig.py","lineNumber":101,"sourceCode":"    if suffixed in _AVAILABLE_SCHEMES:\n        return suffixed\n    if os.name in _AVAILABLE_SCHEMES:  # On Windows, prefx is just called \"nt\".\n        return os.name\n    return \"posix_prefix\"\n\n\ndef _infer_user() -> str:\n    \"\"\"Try to find a user scheme for the current platform.\"\"\"\n    if _PREFERRED_SCHEME_API:\n        return _PREFERRED_SCHEME_API(\"user\")\n    if is_osx_framework() and not running_under_virtualenv():\n        suffixed = \"osx_framework_user\"\n    else:\n        suffixed = f\"{os.name}_user\"\n    if suffixed in _AVAILABLE_SCHEMES:\n        return suffixed\n    if \"posix_user\" not in _AVAILABLE_SCHEMES:  # User scheme unavailable.\n        raise UserInstallationInvalid()\n    return \"posix_user\"\n\n\ndef _infer_home() -> str:\n    \"\"\"Try to find a home for the current platform.\"\"\"\n    if _PREFERRED_SCHEME_API:\n        return _PREFERRED_SCHEME_API(\"home\")\n    suffixed = f\"{os.name}_home\"\n    if suffixed in _AVAILABLE_SCHEMES:\n        return suffixed\n    return \"posix_home\"\n\n\n# Update these keys if the user sets a custom home.\n_HOME_KEYS = [\n    \"installed_base\",\n    \"base\",\n    \"installed_platbase\",","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/locations/_sysconfig.py#L83-L119","documentation":"UserInstallationInvalid raised by _infer_user() when no 'user' installation scheme is available in sysconfig - i.e. neither the platform-specific user scheme nor the 'posix_user' fallback exists. Without a user scheme, pip cannot compute where --user files go, so it refuses.","triggerScenarios":"Reached during get_scheme(..., user=True) when _PREFERRED_SCHEME_API is None, neither f'{os.name}_user' nor 'posix_user' is in sysconfig.get_scheme_names(). Typical of embedded/custom Python builds that ship a stripped-down sysconfig.","commonSituations":"An embedded Python distribution (e.g. python-embed on Windows, some app-bundled interpreters) with no user scheme registered; a stripped sysconfig; installing with --user into such an interpreter.","solutions":["Drop --user and install into the environment's site-packages (or a virtualenv) instead.","Use a standard CPython interpreter that registers the user scheme.","If you control the build, ensure sysconfig exposes a user scheme (do not strip it for embedding).","Install into a venv: python -m venv .venv && .venv/bin/pip install <pkg>."],"exampleFix":"# before\n/embedded/python -m pip install --user somepkg\n\n# after\n/embedded/python -m venv env\nenv/bin/pip install somepkg   # or drop --user","handlingStrategy":"validation","validationCode":"import sysconfig\nschemes = set(sysconfig.get_scheme_names())\nuser_ok = f'{__import__(\"os\").name}_user' in schemes or 'posix_user' in schemes\nprint('user scheme available:', user_ok)","typeGuard":"def user_scheme_available() -> bool:\n    import os, sysconfig\n    s = set(sysconfig.get_scheme_names())\n    return f'{os.name}_user' in s or 'posix_user' in s","tryCatchPattern":"from pip._internal.exceptions import UserInstallationInvalid\ntry:\n    get_scheme(dist_name, user=True)\nexcept UserInstallationInvalid:\n    # fall back to venv or system install\n    ...","preventionTips":["Avoid --user on embedded/custom interpreters lacking a user scheme.","Prefer virtualenvs for isolated installs.","Verify sysconfig scheme availability before scripting --user installs.","Use a standard CPython build for --user support."],"tags":["install-location","user-scheme","sysconfig","embedded"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}