pypa/pip · error · UserInstallationInvalid

User base directory is not specified

Error message

User base directory is not specified

What it means

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.

Source

Thrown at src/pip/_internal/locations/_sysconfig.py:101

    if suffixed in _AVAILABLE_SCHEMES:
        return suffixed
    if os.name in _AVAILABLE_SCHEMES:  # On Windows, prefx is just called "nt".
        return os.name
    return "posix_prefix"


def _infer_user() -> str:
    """Try to find a user scheme for the current platform."""
    if _PREFERRED_SCHEME_API:
        return _PREFERRED_SCHEME_API("user")
    if is_osx_framework() and not running_under_virtualenv():
        suffixed = "osx_framework_user"
    else:
        suffixed = f"{os.name}_user"
    if suffixed in _AVAILABLE_SCHEMES:
        return suffixed
    if "posix_user" not in _AVAILABLE_SCHEMES:  # User scheme unavailable.
        raise UserInstallationInvalid()
    return "posix_user"


def _infer_home() -> str:
    """Try to find a home for the current platform."""
    if _PREFERRED_SCHEME_API:
        return _PREFERRED_SCHEME_API("home")
    suffixed = f"{os.name}_home"
    if suffixed in _AVAILABLE_SCHEMES:
        return suffixed
    return "posix_home"


# Update these keys if the user sets a custom home.
_HOME_KEYS = [
    "installed_base",
    "base",
    "installed_platbase",

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Drop --user and install into the environment's site-packages (or a virtualenv) instead.
2. Use a standard CPython interpreter that registers the user scheme.
3. If you control the build, ensure sysconfig exposes a user scheme (do not strip it for embedding).
4. Install into a venv: python -m venv .venv && .venv/bin/pip install <pkg>.

Example fix

# before
/embedded/python -m pip install --user somepkg

# after
/embedded/python -m venv env
env/bin/pip install somepkg   # or drop --user

import sysconfig
schemes = set(sysconfig.get_scheme_names())
user_ok = f'{__import__("os").name}_user' in schemes or 'posix_user' in schemes
print('user scheme available:', user_ok)

def user_scheme_available() -> bool:
    import os, sysconfig
    s = set(sysconfig.get_scheme_names())
    return f'{os.name}_user' in s or 'posix_user' in s

from pip._internal.exceptions import UserInstallationInvalid
try:
    get_scheme(dist_name, user=True)
except UserInstallationInvalid:
    # fall back to venv or system install
    ...

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot set --user and --prefix together
• Cannot set --home and --prefix together
• Unknown platform: {os.name} Can not change root path prefix
• invalid sysconfig.get_config_var('EXT_SUFFIX')

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