GNOME Keyring is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."
installed on its own. should also be installed to grant other applications access to your keyrings. Although is deprecated (and superseded by libsecret), it may still be required by certain applications.is a member of the group is thus usually present on systems running GNOME. The package can otherwise be
Extra utilities related to GNOME Keyring include:
- secret-tool — Access the GNOME Keyring (and any other service implementing the DBus Secret Service API) from the command line.
- lssecret — List all secret items using libsecret (e.g. GNOME Keyring).
- gnome-keyring-query — Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring.
Manage using GUI
You can manage the contents of GNOME Keyring using Seahorse; install the package.
Using the keyring
The PAM module pam_gnome_keyring.so initialises GNOME Keyring partially, unlocking the default login keyring in the process. It should be followed by a call to gnome-keyring-daemon with the
--start option to complete initialisation and to set environment variables.
- To use automatic unlocking with automatic login, you can set a blank password for the default keyring. Note that the contents of the keyring are stored unencrypted in this case.
- Alternatively, if using GDM and LUKS, GDM can unlock your keyring if it matches your LUKS password. For this to work, you need to use the systemd init in your mkinitcpio.conf as well as the appropriate kernel parameters. See  for more details.
- Skipping the PAM step works, because the next step will initialise the daemon when one is not running already; however, the default keyring is not unlocked in this case. More details are available at .
When using a display manager, the keyring works out of the box for most cases. GDM, LightDM, LXDM, and SDDM already have the necessary PAM configuration. For a display manager that does not automatically unlock the keyring edit the appropriate file instead of
/etc/pam.d/login as mentioned below.
When using console-based login, edit
auth optional pam_gnome_keyring.so at the end of the
auth section and
session optional pam_gnome_keyring.so auto_start at the end of the
#%PAM-1.0 auth required pam_securetty.so auth requisite pam_nologin.so auth include system-local-login auth optional pam_gnome_keyring.so account include system-local-login session include system-local-login session optional pam_gnome_keyring.so auto_start
If you are using GNOME, Unity, Cinnamon, or MATE, you are done. The initialisation is completed and environment variables are set automatically.
If you are not using GNOME, Unity, Mate, or Cinnamon as your desktop environment, initialisation will not complete automatically. You can fix this using various methods:
Add the following to your
~/.zshenv, or similar:
if [ -n "$DESKTOP_SESSION" ];then eval $(gnome-keyring-daemon --start) export SSH_AUTH_SOCK fi
if test -n "$DESKTOP_SESSION" set -x (gnome-keyring-daemon --start | string split "=") end
Start the gnome-keyring-daemon from xinitrc:
eval $(gnome-keyring-daemon --start) export SSH_AUTH_SOCK
See Xfce#SSH agents for use in Xfce.
~/.config/autostart/ and delete the
OnlyShowIn=GNOME;Unity;MATE;Cinnamon; lines from each file. Note however that this will not set
SSH_AUTH_SOCK (and the other variables if the PAM step was skipped) environment variable.
gnome-keyring-daemon with the ssh component will start an SSH agent and automatically load all the keys in
~/.ssh/ that have corresponding .pub files. There is no way to remove these keys from the agent.
To list all loaded keys:
$ ssh-add -L
When you connect to a server that uses a loaded key with a password, a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!
To permanently save the a passphrase in the keyring, use ssh-askpass from thepackage:
$ /usr/lib/seahorse/ssh-askpass my_key
To manually add an SSH key from another directory:
$ ssh-add ~/.private/id_rsa Enter passphrase for ~/.private/id_rsa:
~/.ssh/id_rsa.pubin the example). Also, make sure that the public key is the file name of the private key plus .pub (for example,
To disable all manually added keys:
$ ssh-add -D
Disable keyring daemon components
If you wish to run an alternative SSH agent (e.g. ssh-agent or gpg-agent), you need to disable the
ssh component of GNOME Keyring. To do so in an account-local way, copy
~/.config/autostart/ and then append the line
Hidden=true to the copied file. Then log out.
SSH_AUTH_SOCKto point to gnome-keyring regardless if it is running or not. To prevent this, you need to set the environment variable GSM_SKIP_SSH_AGENT_WORKAROUND before gnome-shell is started. One way to do this is to add the following line to
Tips and tricks
Integration with applications
$ gnome-keyring-daemon -r -d
This command starts gnome-keyring-daemon, shutting down previously running instances.
The GNOME keyring is useful in conjunction with Git when you are pushing over HTTPS. The package needs to be installed for this functionality to be available.
Configure Git to use the libsecret helper:
$ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret
The next time you run
git push, you will be asked to unlock your keyring if it is not already unlocked.
Several applications which use GnuPG require a
pinentry-program to be set. Set the following to use GNOME 3 pinentry for GNOME Keyring to manage passphrase prompts.
Another option is to force loopback for GPG which should allow the passphrase to be entered in the application.
Renaming a keyring
The display name for a keyring (i.e., the name that appears in Seahorse and from
file) can be changed by changing the value of display-name in the unencrypted keyring file. Keyrings will usually be stored in
~/.local/share/keyrings/ with the .keyring file extension.
Automatically change keyring password with user password
password optional pam_gnome_keyring.so to the end of
#%PAM-1.0 #password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3 #password required pam_unix.so sha512 shadow use_authtok password required pam_unix.so sha512 shadow nullok password optional pam_gnome_keyring.so
Passwords are not remembered
If you are prompted for a password after logging in and you find that your passwords are not saved, then you may need to create/set a default keyring. To do this using Seahorse (a.k.a. Passwords and Keys), see Create a new keyring and Change the default keyring in GNOME Help.
Resetting the keyring
You will need to change your login keyring password if you receive the following error message: "The password you use to login to your computer no longer matches that of your login keyring".
Alternatively, you can remove the
user.keystore files from
~/.local/share/keyrings/. Be warned that this will permanently delete all saved keys. After removing the files, simply log out and log in again.
Unable to locate daemon control file
The following error may appear in the journal after logging in:
gkr-pam: unable to locate daemon control file
This message "can be safely ignored" if there are no other related issues .