Table of Contents
- Installing and Using Python Keyring Lib
- What is Python keyring lib?
- Installation Instructions
- Using Keyring
- Configure your keyring lib
- Integrate the keyring lib with your application
- Get involved
The Python keyring lib provides a easy way to access the system keyring service from python. It can be used in any application that needs safe password storage.
The keyring library is licensed under both the MIT license and the PSF license.
These recommended keyring backends are supported by the Python keyring lib:
- Mac OS X Keychain
- Freedesktop Secret Service (requires secretstorage)
- KWallet (requires dbus)
- Windows Credential Vault
Other keyring implementations are provided in the keyrings.alt package.
Install from Index
Install using your favorite installer. For example:
$ pip install keyring
On Linux, the recommended keyring relies on SecretStorage, which in turn relies on dbus-python, but dbus-python does not install correctly when using the Python installers, so dbus-python must be installed as a system package. See the SecretStorage GitHub repo for details.
The basic usage of keyring is pretty simple: just call keyring.set_password and keyring.get_password:
>>> import keyring >>> keyring.set_password("system", "username", "password") >>> keyring.get_password("system", "username") 'password'
Keyring supplies a
keyring command which is installed with the
package. After installing keyring in most environments, the
command should be available for setting, getting, and deleting
passwords. For more information on usage, invoke with no arguments
--help as so:
$ keyring --help $ keyring set system username Password for 'username' in 'system': $ keyring get system username password
The command-line functionality is also exposed as an executable package, suitable for invoking from Python like so:
$ python -m keyring --help $ python -m keyring set system username Password for 'username' in 'system': $ python -m keyring get system username password
The python keyring lib contains implementations for several backends. The
automatically choose the keyring that is most suitable for your current
environment. You can also specify the keyring you like to be used in the
config file or by calling the
This section describes how to change your option in the config file.
The configuration of the lib is stored in a file named "keyringrc.cfg". This file must be found in a platform-specific location. To determine where the config file is stored, run the following:
python -c "import keyring.util.platform_; print(keyring.util.platform_.config_root())"
Some keyrings also store the keyring data in the file system. To determine where the data files are stored, run this command:
python -c "import keyring.util.platform_; print(keyring.util.platform_.data_root())"
To specify a keyring backend, set the default-keyring option to the
full path of the class for that backend, such as
If keyring-path is indicated, keyring will add that path to the Python module search path before loading the backend.
For example, this config might be used to load the SimpleKeyring from the demo directory in the project checkout:
[backend] default-keyring=simplekeyring.SimpleKeyring keyring-path=/home/kang/pyworkspace/python-keyring-lib/demo/
The interface for the backend is defined by
Every backend should derive from that base class and define a
attribute and three functions:
backend module for more detail on the interface of this class.
Keyring additionally allows programmatic configuration of the
backend calling the api
set_keyring(). The indicated backend
will subsequently be used to store and retrieve passwords.
Here's an example demonstrating how to invoke
# define a new keyring class which extends the KeyringBackend import keyring.backend class TestKeyring(keyring.backend.KeyringBackend): """A test keyring which always outputs same password """ priority = 1 def set_password(self, servicename, username, password): pass def get_password(self, servicename, username): return "password from TestKeyring" def delete_password(self, servicename, username, password): pass # set the keyring for keyring lib keyring.set_keyring(TestKeyring()) # invoke the keyring lib try: keyring.set_password("demo-service", "tarek", "passexample") print("password stored sucessfully") except keyring.errors.PasswordSetError: print("failed to store password") print("password", keyring.get_password("demo-service", "tarek"))
The following is a complete transcript for installing keyring in a virtual environment on Ubuntu 16.04. No config file was used.:
$ sudo apt install python3-venv libdbus-glib-1-dev $ cd /tmp $ pyvenv py3 $ source py3/bin/activate $ pip install -U pip $ pip install secretstorage dbus-python $ pip install keyring $ python >>> import keyring >>> keyring.get_keyring() <keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8> >>> keyring.set_password("system", "username", "password") >>> keyring.get_password("system", "username") 'password'
It is possible to use the SecretService backend on Linux systems without X11 server available (only D-Bus is required). To do that, you need the following:
Install the GNOME Keyring daemon.
Start a D-Bus session, e.g. run
dbus-run-session -- shand run the following commands inside that shell.
--unlockoption. The description of that option says:
Read a password from stdin, and use it to unlock the login keyring or create it if the login keyring does not exist.
When that command is started, enter your password into stdin and press Ctrl+D (end of data). After that the daemon will fork into background (use
--foregroundoption to prevent that).
Now you can use the SecretService backend of Keyring. Remember to run your application in the same D-Bus session as the daemon.
The keyring lib has a few functions:
get_keyring(): Return the currently-loaded keyring implementation.
get_password(service, username): Returns the password stored in the active keyring. If the password does not exist, it will return None.
set_password(service, username, password): Store the password in the keyring.
delete_password(service, username): Delete the password stored in keyring. If the password does not exist, it will raise an exception.
Python keyring lib is an open community project and highly welcomes new contributors.
- Repository: https://github.com/jaraco/keyring/
- Bug Tracker: https://github.com/jaraco/keyring/issues/
- Mailing list: http://groups.google.com/group/python-keyring
This project makes use of automated releases via Travis-CI. The simple workflow is to tag a commit and push it to Github. If it passes tests on a late Python version, it will be automatically deployed to PyPI.
Other things to consider when making a release:
- first ensure that tests pass (preferably on Windows and Linux)
- check that the changelog is current for the intended release
Tests are continuously run using Travis-CI.
To run the tests yourself, you'll want keyring installed to some environment in which it can be tested. Recommended technique is described below.
Keyring prefers use of tox <https://pypi.org/project/tox> to run tests.
Simply install and invoke
This technique is the one used by the Travis-CI script.