From ArchWiki
Jump to navigation Jump to search

GNOME Keyring is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."


gnome-keyring is a member of the gnome group is thus usually present on systems running GNOME. The package can otherwise be installed on its own. libsecret should also be installed to grant other applications access to your keyrings. Although libgnome-keyring is deprecated (and superseded by libsecret), it may still be required by certain applications.

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. || libsecret
  • lssecret — List all secret items using libsecret (e.g. GNOME Keyring). || lssecret-gitAUR
  • gnome-keyring-query — Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring. (archived) || gnome-keyring-queryAUR
Note: gnome-keyring-query only requires libgnome-keyring as a build dependency.

Manage using GUI

You can manage the contents of GNOME Keyring using Seahorse; install the seahorse package.

Passwords for keyrings (e.g., the default keyring, "Login") can be changed and even removed. See Create a new keyring and Update the keyring password in GNOME Help for more information.

Using the keyring outside of GNOME

Without a display manager

Automatic login

If you are using automatic login, then you can disable the keyring manager by setting a blank password on the login keyring.

Note: The passwords are stored unencrypted in this case.

Console login

When using console-based login, the keyring daemon can be started by either PAM or xinitrc. PAM can also unlock the keyring automatically at login.

PAM method

Start the gnome-keyring-daemon from /etc/pam.d/login:

Add auth optional at the end of the auth section and session optional auto_start at the end of the session section.

auth       required
auth       requisite
auth       include      system-local-login
auth       optional
account    include      system-local-login
session    include      system-local-login
session    optional auto_start

For SDDM, the file /etc/pam.d/sddm already comes with the necessary changes.

Next, for GDM, add password optional to the end of /etc/pam.d/passwd.


#password	required difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
#password	required sha512 shadow use_authtok
password	required sha512 shadow nullok
password	optional
  • To use automatic unlocking, the same password for the user account and the keyring have to be set.
  • You will still need the code in ~/.xinitrc below in order to export the environment variables required.
xinitrc method

Start the gnome-keyring-daemon from xinitrc:

eval $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)

See Xfce#SSH agents for use in Xfce.

With a display manager

When using a display manager, the keyring works out of the box for most cases. The following display managers automatically unlock the keyring once you log in:

One notable exception is SDDM in combination with the KDE Plasma desktop environment, which in its default configuration on many systems automatically unlocks KWallet but not the GNOME keyring. To fix this, edit /etc/pam.d/sddm and add

auth      optional

to the very end of the auth section and

session   optional auto_start

to the end of the session section.

Should the same issue arise with another display manager, it can be fixed by doing the above in the corresponding file under /etc/pam.d/.

Automatic login

For GDM, the keyring's file name must be login.keyring to be automatically unlocked. GNOME will automatically create this keyring upon login.

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.

Terminal applications

To enable the keyring for applications run through the terminal, such as SSH, add the following to your ~/.bash_profile, ~/.zshenv, or similar:

if [ -n "$DESKTOP_SESSION" ];then
    eval $(gnome-keyring-daemon --start)
    export SSH_AUTH_SOCK
if test -n "$DESKTOP_SESSION"
    set -x (gnome-keyring-daemon --start | string split "=")

SSH keys

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 the seahorse package:

$ /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:
Note: You have to have the corresponding .pub file in the same directory as the private key (~/.ssh/ in 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

Start SSH and Secrets components of keyring daemon

If you are starting GNOME Keyring with a display manager or the PAM method described in #PAM method and you are not using GNOME, Unity, Mate, or Cinnamon as your desktop environment, you may find that the SSH agent and Secret Service components are not started automatically. You can fix this by copying the gnome-keyring-ssh.desktop and gnome-keyring-secrets.desktop files from /etc/xdg/autostart/ to ~/.config/autostart/ and by deleting the OnlyShowIn=GNOME;Unity;MATE;Cinnamon; lines from each file.

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 /etc/xdg/autostart/gnome-keyring-ssh.desktop to ~/.config/autostart/ and then append the line Hidden=true to the copied file. Then log out.

Note: In case you use GNOME 3.24 or older on Wayland, gnome-shell will overwrite SSH_AUTH_SOCK to 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 ~/.pam_environment:

Tips and tricks

Integration with applications

Flushing passphrases

$ gnome-keyring-daemon -r -d

This command starts gnome-keyring-daemon, shutting down previously running instances.

Git integration

The GNOME keyring is useful in conjunction with Git when you are pushing over HTTPS. libsecret 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.

GnuPG integration

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.

pinentry-program /usr/bin/pinentry-gnome3

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.


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 login.keyring and 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.

See also