SecretStorage

What it is and what it does

SecretStorage is a Python library that wraps the FreeDesktop.org Secret Service API, allowing your code to store and retrieve passwords and other secrets through the system's native credential management services. It works with GNOME Keyring, KWallet, and KeePassXC, providing a unified interface to create, edit, and delete secret items organized into collections. The library handles the D-Bus communication and cryptographic operations needed to interact with these services securely.

You would use this when you need your Python application to store sensitive data (API keys, database passwords, OAuth tokens) in the user's system keyring rather than in plaintext config files or environment variables. It requires Python 3.10 or later and depends on cryptography for encryption and jeepney for D-Bus communication. The package is stable and actively maintained, though it is Linux/POSIX-focused and requires a running Secret Service daemon.

Use it for

• Store API credentials in GNOME Keyring so a Python CLI tool can retrieve them securely without hardcoding
• Build a password manager or credential sync tool that integrates with the system's native secret storage
• Manage OAuth tokens in KWallet for a desktop application that needs to authenticate with external services
• Organize application secrets into collections for better credential lifecycle management
• Retrieve stored secrets programmatically in a headless service that has D-Bus access to a keyring daemon

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

secretstorage on PyPI

Before you install

Low friction installation with two straightforward dependencies (cryptography and jeepney). Package is in production/stable status with recent activity (last commit 2026-01-31) and no known vulnerabilities, though maintenance is aging.

Requires a running D-Bus session and Secret Service daemon (e.g., GNOME Keyring); will fail on Windows/macOS or headless systems without D-Bus. Python >= 3.10 required.

License in practice

BSD-3-Clause (permissive) license allows use in most projects without significant restrictions, though you should review the full license text if incorporating into proprietary software.

Quickstart

pip install secretstorage

import secretstorage

# Open the default collection
collection = secretstorage.get_default_collection()

# Store a secret
collection.create_item('my-password', b'secret-value', {'app': 'myapp'})

# Retrieve a secret
items = collection.search_items({'app': 'myapp'})
for item in items:
    print(item.get_secret())

Package facts

Evidence: secretstorage-3.5.0-py3-none-any.whl

Tags

More Python Modules packages

See also keyring · keyrings.cryptfile · azure-keyvault-secrets · google-cloud-secret-manager · keyrings.alt · onepassword-sdk · credstash · robocorp-vault · aws-encryption-sdk · pqcrypto