pypa/pip · error · UserInstallationInvalid

User base directory is not specified

Error message

User base directory is not specified

What it means

Raised as UserInstallationInvalid (defined in exceptions.py:276, str returns 'User base directory is not specified') from _infer_user in _sysconfig.py:100-101. It occurs when a --user install is requested but no usable user installation scheme exists: neither the platform-specific user scheme nor the fallback 'posix_user' is present in the available sysconfig schemes, which typically means the user base directory (PYTHONUSERBASE / default user site) is not configured.

Solutions

1. Drop --user and install into a virtualenv (python -m venv) instead.
2. Set PYTHONUSERBASE to a writable directory and ensure the interpreter supports user-site installs.
3. Use --target <dir> or --prefix <dir> to install into an explicit location.

Example fix

// before
pip install --user mypkg
// after
python -m venv .venv && .venv/bin/pip install mypkg

// Before --user, check a user scheme is available:
import sysconfig, site
if not site.ENABLE_USER_SITE or 'posix_user' not in sysconfig.get_scheme_names():
    raise SystemExit('user install unsupported here; use a venv or --prefix')

from pip._internal.exceptions import UserInstallationInvalid
try:
    scheme = get_scheme(dist, user=True)
except UserInstallationInvalid:
    # fall back to a venv or --prefix/--target
    ...

When it happens

Trigger: Calling get_scheme(..., user=True) (i.e. pip install --user) on an interpreter where sysconfig has no '*_user' scheme and 'posix_user' is not in _AVAILABLE_SCHEMES, so _infer_user falls through to raise UserInstallationInvalid().

Common situations: Running --user inside certain embedded/bundled Python distributions that ship a reduced sysconfig; a Python build where ENABLE_USER_SITE is disabled and user site-packages are unavailable; misconfigured PYTHONUSERBASE pointing nowhere.

Related errors

• Cannot set --home and --prefix together
• Cannot set --user and --prefix together
• Unknown platform: Can not change root path prefix on…
• Cannot determine archive format of
• Could not install locked package

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

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