python-poetry/poetry · error · PoetryKeyringError

Access to keyring was requested, but it is not available

Error message

Access to keyring was requested, but it is not available

What it means

The PasswordManager.keyring cached property raises PoetryKeyringError when use_keyring is false, i.e. when config keyring.enabled is false OR PoetryKeyring.is_available() returned false (no importable keyring, only an unsuitable backend such as chainer/fail/null/plaintext, or the availability probe failed). It guards callers from touching the keyring object when it cannot be used.

Source

Thrown at src/poetry/utils/password_manager.py:202

                "Accessing keyring failed during availability check", exc_info=True
            )
            return False

        return True


class PasswordManager:
    def __init__(self, config: Config) -> None:
        self._config = config

    @atomic_cached_property
    def use_keyring(self) -> bool:
        return self._config.get("keyring.enabled") and PoetryKeyring.is_available()

    @atomic_cached_property
    def keyring(self) -> PoetryKeyring:
        if not self.use_keyring:
            raise PoetryKeyringError(
                "Access to keyring was requested, but it is not available"
            )

        return PoetryKeyring("poetry-repository")

    @staticmethod
    def warn_plaintext_credentials_stored() -> None:
        logger.warning("Using a plaintext file to store credentials")

    def set_pypi_token(self, repo_name: str, token: str) -> None:
        if not self.use_keyring:
            self.warn_plaintext_credentials_stored()
            self._config.auth_config_source.add_property(
                ["pypi-token", repo_name], token
            )
        else:
            self.keyring.set_password(repo_name, "__token__", token)

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Guard access with `manager.use_keyring` (or PoetryKeyring.is_available()) before touching `manager.keyring`.
2. Enable the keyring (`poetry config keyring.enabled true`) and install/configure a usable backend (Secret Service, macOS Keychain, etc.).
3. Run the preflight check (PoetryKeyring.preflight_check) to see why availability failed (debug logs explain the rejected backend).
4. If keyring is intentionally disabled, route credential storage through config/env instead.

Example fix

# before
kr = manager.keyring  # raises when keyring disabled/unavailable
# after
if manager.use_keyring:
    kr = manager.keyring
    kr.set_password(name, user, pw)
else:
    manager.warn_plaintext_credentials_stored()
    manager._config.auth_config_source.add_property(["pypi-token", name], pw)

from poetry.utils.password_manager import PasswordManager, PoetryKeyring

# check both config flag and actual availability before touching .keyring
if not (manager._config.get('keyring.enabled') and PoetryKeyring.is_available()):
    raise RuntimeError('keyring not available; use config/env')

from poetry.utils.password_manager import PoetryKeyringError
try:
    kr = manager.keyring
except PoetryKeyringError:
    # fall back to non-keyring credential storage
    kr = None

When it happens

Trigger: Accessing PasswordManager.keyring (directly or via set_pypi_token/get_pypi_token paths that require it) while keyring is disabled in config or no suitable backend is available on the host.

Common situations: keyring.enabled set to false but code path still requests the keyring; headless box where is_available() is false (only plaintext/null backend); user disabled keyring to avoid plaintext storage.

Related errors

• Unable to retrieve the password for {name} from the key ring
• Unable to store the password for {name} in the key ring: {e}
• Unable to delete the password for {name} from the key ring
• The PyPI repository cannot be configured with a custom url.
• Missing [url] in source {name!r}.

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/f565396fb812a8d8.json. Report an issue: GitHub.