SecretStorage

3.5.0 verified Tue May 12 auth: no python install: verified quickstart: stale

SecretStorage is a Python library that provides secure storage for passwords and other secrets using the FreeDesktop.org Secret Service API. The current version is 3.5.0, released on November 23, 2025. It requires Python 3.10 or higher and has a stable release cadence with regular updates addressing security and functionality improvements.

pip install SecretStorage

Common errors

error ModuleNotFoundError: No module named 'secretstorage' ↓

cause The 'secretstorage' package is not installed in the current Python environment.

fix

pip install secretstorage

error secretstorage.exceptions.NoBackendError: No backend available. ↓

cause The 'secretstorage' library could not find or connect to any FreeDesktop.org Secret Service implementation (like gnome-keyring or KDE KWallet) via D-Bus.

fix

Ensure a Secret Service backend (e.g., 'gnome-keyring-daemon') is running and accessible on the D-Bus session. This often requires being logged into a desktop environment or setting up the service explicitly in headless environments.

error secretstorage.exceptions.SecretStorageException: Cannot connect to the secret service. ↓

cause The 'secretstorage' library failed to establish a D-Bus connection to the FreeDesktop.org Secret Service, possibly due to the service not running, D-Bus issues, or permission problems.

fix

Verify that a Secret Service backend (e.g., 'gnome-keyring-daemon') is installed, running, and accessible. Restarting your desktop environment or ensuring the D-Bus session is properly configured often resolves this.

error dbus.exceptions.DBusException: org.freedesktop.Secret.Error.NoCollection ↓

cause The requested secret collection (e.g., 'login') does not exist or is not available on the Secret Service backend.

fix

Create the collection if it's missing (e.g., through a desktop GUI like 'seahorse' or via 'secretstorage.collection.create_collection()') or ensure the correct collection name is being used.

Warnings

breaking Python 3.10 or higher is required starting from version 3.4.0 ↓

fix Upgrade to Python 3.10 or higher

deprecated The int_to_bytes() function was removed in version 3.5.0 ↓

fix Use the built-in int.to_bytes() method instead

gotcha The secretstorage library failed to initialize D-Bus communication because the DBUS_SESSION_BUS_ADDRESS environment variable was not set. ↓

fix Ensure the DBUS_SESSION_BUS_ADDRESS environment variable is properly configured in the execution environment. This typically involves running within a graphical desktop session or explicitly setting the variable (e.g., from `dbus-daemon --session --print-address` output) for headless environments.

breaking Secretstorage requires a D-Bus session to be active, and the `DBUS_SESSION_BUS_ADDRESS` environment variable is not set, preventing D-Bus connection. ↓

fix Ensure a D-Bus session is available and `DBUS_SESSION_BUS_ADDRESS` is correctly set in the environment. This typically happens automatically in a graphical desktop environment. For headless environments or containers, D-Bus may need to be manually configured and started.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.05s 33.8M

3.10 slim (glibc) - - 0.04s 34M

3.11 alpine (musl) - - 0.07s 36.0M

3.11 slim (glibc) - - 0.07s 36M

3.12 alpine (musl) - - 0.06s 27.7M

3.12 slim (glibc) - - 0.07s 28M

3.13 alpine (musl) - - 0.06s 27.4M

3.13 slim (glibc) - - 0.07s 28M

3.9 alpine (musl) - - 0.05s 34.1M

3.9 slim (glibc) - - 0.04s 34M

Imports

Collection

from secretstorage.collection import Collection

Correct import path for Collection class

Item
```
from secretstorage.item import Item
```
Correct import path for Item class
SecretStorageException
```
from secretstorage.exceptions import SecretStorageException
```
Correct import path for SecretStorageException class

Quickstart stale last tested: 2026-04-23

This script demonstrates how to initialize a D-Bus connection, access the default collection, create a new secret item, and retrieve its secret using the SecretStorage library.

import secretstorage

# Initialize D-Bus connection
connection = secretstorage.dbus_init()

# Access the default collection
collection = secretstorage.get_default_collection(connection)

# Create a new item
attributes = {'application': 'myapp'}
item = collection.create_item('My Secret Item', attributes, b'mysecretpassword')

# Retrieve the secret
secret = item.get_secret()
print(secret.decode())