pypa/pip · error · RuntimeError

should only be used on Unix

Error message

should only be used on Unix

What it means

Raised as RuntimeError by the stub getuid() function defined in platformdirs/unix.py when running on Windows (sys.platform == 'win32'). The module conditionally defines a getuid() that always raises this error, since os.getuid() does not exist on Windows. This stub exists so that Unix-specific code paths fail loudly rather than with an AttributeError.

Solutions

1. Use the platform-appropriate platformdirs class (platformdirs.PlatformDirs auto-selects the correct one).
2. Guard Unix-specific code with `if sys.platform != 'win32'` before calling getuid or Unix-specific APIs.
3. Never import platformdirs.unix directly on Windows; use the top-level platformdirs API.
4. Check platform before accessing _use_site or other uid-dependent properties.

Example fix

// before
from pip._vendor.platformdirs.unix import getuid
uid = getuid()  # RuntimeError on Windows

// after
import sys
if sys.platform != 'win32':
    from pip._vendor.platformdirs.unix import getuid
    uid = getuid()
else:
    uid = None

import sys
def getuid_safe():
    if sys.platform == 'win32':
        return None  # not available on Windows
    from os import getuid
    return getuid()

import sys
def supports_getuid() -> bool:
    return sys.platform != 'win32'

import sys
try:
    from pip._vendor.platformdirs.unix import getuid
    uid = getuid()
except RuntimeError:
    uid = None  # Windows: getuid not available

When it happens

Trigger: Importing and calling platformdirs.unix.getuid() (or code that calls it like _UnixDefaults._use_site) on a Windows system. The conditional at line 19 (`if sys.platform == 'win32'`) installs the raising stub instead of the real os.getuid.

Common situations: Cross-platform code that inadvertently imports or uses the Unix platformdirs implementation on Windows; logic bugs that don't check the platform before accessing Unix-only APIs; running Unix-specific platformdirs code paths due to misconfigured platform detection.

Related errors

• Unknown CSIDL name
• Unset environment variable
• non-local file URIs are not supported on this platform
• SHGetKnownFolderPath returned NULL for
• Can not use any platform or abi specific options unless…

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

Appendix: source

Thrown at src/pip/_vendor/platformdirs/unix.py:23

import os
import sys
from configparser import ConfigParser
from functools import cached_property
from pathlib import Path
from tempfile import gettempdir
from typing import TYPE_CHECKING, NoReturn

from ._xdg import XDGMixin
from .api import PlatformDirsABC

if TYPE_CHECKING:
    from collections.abc import Iterator

if sys.platform == "win32":

    def getuid() -> NoReturn:
        msg = "should only be used on Unix"
        raise RuntimeError(msg)

else:
    from os import getuid


class _UnixDefaults(PlatformDirsABC):  # ruff:ignore[too-many-public-methods]
    """Default directories for Unix/Linux without XDG environment variable overrides.

    The XDG env var handling is in :class:`~platformdirs._xdg.XDGMixin`.

    """

    @cached_property
    def _use_site(self) -> bool:
        return self.use_site_for_root and getuid() == 0

    @property
    def user_data_dir(self) -> str:

View on GitHub (pinned to f399c37189)