pypa/pip · error · RuntimeError

Keyring util is outdated; must be at least version 25.2.1…

Error message

Keyring util is outdated; must be at least version 25.2.1, please upgrade it

What it means

Raised as a RuntimeError by KeyringCliProvider.get_auth_info when the external 'keyring' CLI subprocess exits with code 2 and its stderr contains both 'unrecognized arguments' and '--mode=creds'. pip invokes keyring with the '--mode=creds' flag, which only exists in keyring >= 25.2.1, so this signals an outdated keyring executable on PATH.

Solutions

1. Upgrade keyring: pip install --upgrade 'keyring>=25.2.1'.
2. Verify the version with 'keyring --version' and that the upgraded binary is the one pip discovers (check PATH / which keyring).
3. Pin 'keyring>=25.2.1' in your requirements/constraints so the floor is enforced.
4. If upgrade is impossible, disable the keyring CLI provider via --keyring-provider disabled or pip.conf.

Example fix

# before
$ keyring --version
keyring 20.x

# after
$ pip install -U 'keyring>=25.2.1'
$ keyring --version
keyring 25.2.1

import shutil, subprocess

def keyring_version_ok(minimum=(25, 2, 1)) -> bool:
    exe = shutil.which("keyring")
    if not exe:
        return False
    out = subprocess.run([exe, "--version"], capture_output=True, text=True)
    nums = [int(x) for x in out.stdout.split() if x.split(".")[0].isdigit()][0]
    return tuple(int(x) for x in out.stdout.strip().split()[-1].split(".")) >= minimum

from pip._internal.exceptions import PipError
try:
    pip_command.main(["install", "pkg"])
except RuntimeError as e:
    if "Keyring util is outdated" in str(e):
        # upgrade keyring and retry
        ...
    raise

When it happens

Trigger: pip is configured to fetch credentials via the keyring CLI (keyring_provider auto/subprocess/...) for an authenticated index, and the discovered 'keyring' executable is older than 25.2.1 and rejects the --mode=creds argument.

Common situations: System/virtualenv keyring package outdated relative to pip; multiple keyring installs and the wrong one is first on PATH; CI images shipping an old keyring; fresh containers that install keyring without pinning.

Related errors

• Cannot find command - invalid PATH
• Cannot restore Specifier from
• Cannot restore SpecifierSet from
• Editor Subprocess exited with exit code
• Failed to build ' ' when

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

Appendix: source

Thrown at src/pip/_internal/network/auth.py:154

        env = os.environ.copy()
        env["PYTHONIOENCODING"] = "utf-8"
        res = subprocess.run(  # noqa: UP022
            cmd,
            stdin=subprocess.DEVNULL,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            env=env,
        )

        # Detect if the user is running an outdated version of keyring without support
        # for querying credentials without username
        errs = res.stderr.decode("utf-8")
        if (
            res.returncode == 2
            and "unrecognized arguments" in errs
            and "--mode=creds" in errs
        ):
            raise RuntimeError(
                "Keyring util is outdated; must be at least version 25.2.1, "
                "please upgrade it"
            )

        if res.returncode:
            return None

        data = json.loads(res.stdout.decode("utf-8"))
        return (data["username"], data["password"])

    def _set_password(self, service_name: str, username: str, password: str) -> None:
        """Mirror the implementation of keyring.set_password using cli"""
        if self.keyring is None:
            return None
        env = os.environ.copy()
        env["PYTHONIOENCODING"] = "utf-8"
        subprocess.run(
            [self.keyring, "set", service_name, username],

View on GitHub (pinned to f399c37189)