Keyring: Secure Password Storage

25.7.0 · active · verified Fri Apr 10

Keyring is a Python library that provides an easy way to access the system's keyring service, allowing applications to store and retrieve passwords securely. The current version is 25.7.0, released on September 20, 2023. Keyring follows a regular release cadence, with updates addressing compatibility, security, and functionality improvements.

Common errors

```
RuntimeError: No recommended backend was available. Install a recommended 3rd party backend package; or, install the keyrings.alt package if you want to use the non-recommended backends. See https://pypi.org/project/keyring for details.
```
cause The keyring library could not find or access a suitable system keyring backend on the operating system, often occurring in headless environments, Docker containers, or when necessary system components are not installed or running.

fix Install a recommended backend for your OS (e.g., 'keyrings.alt' for a fallback, or OS-specific packages like 'gnome-keyring' or 'KWallet' on Linux) and ensure the keyring service is running and accessible.
```
keyring.errors.NoKeyringError: No recommended backend was available.
```
cause The keyring library failed to locate an appropriate backend to store or retrieve secrets, which is a specific instance of the 'RuntimeError' when no backend is found.

fix Install a recommended 3rd party backend package such as 'keyrings.alt' (pip install keyrings.alt) or ensure your operating system's native keyring service (like Gnome Keyring on Linux, Keychain on macOS, or Credential Locker on Windows) is installed, configured, and running.
```
ModuleNotFoundError: No module named 'keyring'
```
cause The 'keyring' Python package is not installed in the current Python environment or is not accessible via the Python interpreter being used.

fix Install the keyring package using pip: 'pip install keyring'.
```
Error opening keyring: Specified keyring backend not available
```
cause A keyring backend that was explicitly requested or expected by keyring or a dependent application could not be initialized or accessed, potentially due to misconfiguration, permissions, or missing system components.

fix Verify that the necessary OS-specific keyring components are installed and configured correctly, or try explicitly setting a different backend if available. For CLI tools, specifying '--keyring-type=none' can temporarily bypass keyring storage.
```
AttributeError: 'Keyring' object has no attribute 'name'
```
cause This typically occurs when a wrapping library (like an older version of Poetry) attempts to access an attribute ('name') on a keyring object that no longer exists or has a different name due to an API change in the 'keyring' library.

fix Update the wrapping application or library to a version compatible with your installed 'keyring' version, or check the 'keyring' documentation for current API usage if you are directly interacting with keyring backend objects.

Warnings

gotcha On macOS, importing keyring may produce dbus-related warnings if dbus is not properly configured.
Fix: Ensure that dbus is correctly installed and configured on your system to avoid these warnings.
breaking Keyring requires an external backend package (e.g., `keyrings.alt`, `keyrings.gnome`) to store credentials. If no compatible backend is installed or detected, it will raise a `NoKeyringError`. This can occur in fresh environments or if backend dependencies become incompatible (e.g., after a Python version upgrade).
Fix: Install a recommended 3rd party backend package such as `keyrings.alt` to enable Keyring functionality. If issues persist after a Python upgrade, ensure all Keyring backend dependencies are compatible and up-to-date.
breaking Keyring raises NoKeyringError when no suitable backend is installed or found, preventing the storage and retrieval of passwords.
Fix: Install a recommended backend package, such as 'keyrings.alt' for cross-platform compatibility, or 'SecretStorage' on Linux with Secret Service. For example: `pip install keyrings.alt`.

Install

pip install keyring Install Keyring

Imports

keyring
```
import keyring
```
Standard import statement for the Keyring library

Quickstart

A simple example demonstrating how to set and retrieve passwords using the Keyring library.

import keyring

# Set a password
keyring.set_password('system', 'username', 'password')

# Retrieve a password
retrieved_password = keyring.get_password('system', 'username')
print(retrieved_password)

view raw JSON →