{"id":372,"library":"secretstorage","title":"SecretStorage","description":"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.","status":"active","version":"3.5.0","language":"python","source_language":"en","source_url":"https://github.com/mitya57/secretstorage","tags":["security","passwords","secrets","D-Bus","Python"],"install":[{"cmd":"pip install SecretStorage","lang":"bash","label":"Install SecretStorage"}],"dependencies":[{"reason":"Required for D-Bus communication","package":"Jeepney"},{"reason":"Provides cryptographic recipes and primitives","package":"cryptography"}],"imports":[{"note":"Correct import path for Collection class","symbol":"Collection","correct":"from secretstorage.collection import Collection"},{"note":"Correct import path for Item class","symbol":"Item","correct":"from secretstorage.item import Item"},{"note":"Correct import path for SecretStorageException class","symbol":"SecretStorageException","correct":"from secretstorage.exceptions import SecretStorageException"}],"quickstart":{"code":"import secretstorage\n\n# Initialize D-Bus connection\nconnection = secretstorage.dbus_init()\n\n# Access the default collection\ncollection = secretstorage.get_default_collection(connection)\n\n# Create a new item\nattributes = {'application': 'myapp'}\nitem = collection.create_item('My Secret Item', attributes, b'mysecretpassword')\n\n# Retrieve the secret\nsecret = item.get_secret()\nprint(secret.decode())","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.10 or higher","message":"Python 3.10 or higher is required starting from version 3.4.0","severity":"breaking","affected_versions":"3.4.0 and above"},{"fix":"Use the built-in int.to_bytes() method instead","message":"The int_to_bytes() function was removed in version 3.5.0","severity":"deprecated","affected_versions":"3.5.0"},{"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.","message":"The secretstorage library failed to initialize D-Bus communication because the DBUS_SESSION_BUS_ADDRESS environment variable was not set.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Secretstorage requires a D-Bus session to be active, and the `DBUS_SESSION_BUS_ADDRESS` environment variable is not set, preventing D-Bus connection.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T13:21:11.946Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install secretstorage","cause":"The 'secretstorage' package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'secretstorage'"},{"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.","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.","error":"secretstorage.exceptions.NoBackendError: No backend available."},{"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.","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.","error":"secretstorage.exceptions.SecretStorageException: Cannot connect to the secret service."},{"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.","cause":"The requested secret collection (e.g., 'login') does not exist or is not available on the Secret Service backend.","error":"dbus.exceptions.DBusException: org.freedesktop.Secret.Error.NoCollection"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2,"disk_size":"33.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"34M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.2,"disk_size":"36.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.2,"disk_size":"36M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.9,"disk_size":"27.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":1.9,"disk_size":"28M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.1,"disk_size":"27.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":1.9,"disk_size":"28M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2,"disk_size":"34.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"34M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}