pypa/pip · warning · OSError

{path} is a symlink; Will not return uid for symlinks

Error message

{path} is a symlink; Will not return uid for symlinks

What it means

get_path_uid raises OSError (on platforms lacking os.O_NOFOLLOW — AIX and Jython) when the path being checked is a symlink. The function deliberately refuses to follow symlinks so that a symlinked cache dir cannot be used to trick pip's ownership check. On platforms with O_NOFOLLOW the open() itself fails instead.

Source

Thrown at src/pip/_internal/utils/compat.py:66

        https://github.com/pypa/pip/pull/935#discussion_r5307003

    Placed this function in compat due to differences on AIX and
    Jython, that should eventually go away.

    :raises OSError: When path is a symlink or can't be read.
    """
    if hasattr(os, "O_NOFOLLOW"):
        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
        file_uid = os.fstat(fd).st_uid
        os.close(fd)
    else:  # AIX and Jython
        # WARNING: time of check vulnerability, but best we can do w/o NOFOLLOW
        if not os.path.islink(path):
            # older versions of Jython don't have `os.fstat`
            file_uid = os.stat(path).st_uid
        else:
            # raise OSError for parity with os.O_NOFOLLOW above
            raise OSError(f"{path} is a symlink; Will not return uid for symlinks")
    return file_uid


# The importlib.resources.open_text function was deprecated in 3.11 with suggested
# replacement we use below.
if sys.version_info < (3, 11):
    open_text_resource = importlib.resources.open_text
else:

    def open_text_resource(
        package: str, resource: str, encoding: str = "utf-8", errors: str = "strict"
    ) -> IO[str]:
        return (importlib.resources.files(package) / resource).open(
            "r", encoding=encoding, errors=errors
        )


if sys.version_info >= (3, 11):

View on GitHub (pinned to d7d0d0a394)

Solutions

Replace the symlinked cache/site directory with a real directory (copy contents, remove symlink).
Point PIP_CACHE_DIR / the relevant path at a non-symlink directory.
If a symlink is unavoidable on AIX/Jython, use a platform with O_NOFOLLOW (standard CPython on Linux/macOS/BSD).

Example fix

# before - $XDG_CACHE_HOME/pip is a symlink on AIX/Jython
ln -s /mnt/bigcache/pip ~/.cache/pip
pip install pkg

# after - use a real directory
rm ~/.cache/pip
mkdir -p /mnt/bigcache/pip
export PIP_CACHE_DIR=/mnt/bigcache/pip
pip install pkg

Defensive patterns

Strategy: validation

Validate before calling

import os

def ensure_real_cache_dir(cache_dir):
    if os.path.islink(cache_dir):
        raise SystemExit(
            f"refusing to use symlinked cache dir {cache_dir}; use a real directory"
        )
# call at startup on platforms that may lack os.O_NOFOLLOW (AIX/Jython)

Try / catch

try:
    get_path_uid(cache_dir)
except OSError as e:
    if 'symlink' in str(e):
        cache_dir = realpath_nonsymlink(cache_dir)
    else:
        raise

Prevention

Point PIP_CACHE_DIR at a real directory, not a symlink.
On AIX/Jython, prefer standard CPython which has O_NOFOLLOW.
Avoid symlinking venv/cache dirs across volumes.

When it happens

Trigger: hasattr(os,'O_NOFOLLOW') is False (AIX/Jython) and os.path.islink(path) is True. Called from cache-dir/user-site ownership validation when that directory (or a parent) is a symlink.

Common situations: Symlinking $XDG_CACHE_HOME/pip or a virtualenv's cache to another volume on AIX; Jython users; docker images that symlink /root/.cache. On mainstream Linux/macOS/Windows this branch is unreachable.

Related errors

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