keyring

Store and access your passwords safely.

Description

.. image:: https://img.shields.io/pypi/v/keyring.svg
   :target: https://pypi.org/project/keyring

.. image:: https://img.shields.io/pypi/pyversions/keyring.svg

.. image:: https://github.com/jaraco/keyring/actions/workflows/main.yml/badge.svg
   :target: https://github.com/jaraco/keyring/actions?query=workflow%3A%22tests%22
   :alt: tests

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff

.. image:: https://readthedocs.org/projects/keyring/badge/?version=latest
   :target: https://keyring.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2025-informational
   :target: https://blog.jaraco.com/skeleton

.. image:: https://tidelift.com/badges/package/pypi/keyring
   :target: https://tidelift.com/subscription/pkg/pypi-keyring?utm_source=pypi-keyring&utm_medium=readme

.. image:: https://badges.gitter.im/jaraco/keyring.svg
   :alt: Join the chat at https://gitter.im/jaraco/keyring
   :target: https://gitter.im/jaraco/keyring?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

The Python keyring library provides an easy way to access the
system keyring service from python. It can be used in any
application that needs safe password storage.

These recommended keyring backends are supported:

* macOS `Keychain
  <https://en.wikipedia.org/wiki/Keychain_%28software%29>`_
* Freedesktop `Secret Service
  <http://standards.freedesktop.org/secret-service/>`_ supports many DE including
  GNOME (requires `secretstorage <https://pypi.python.org/pypi/secretstorage>`_)
* KDE4 & KDE5 `KWallet <https://en.wikipedia.org/wiki/KWallet>`_
  (requires `dbus <https://pypi.python.org/pypi/dbus-python>`_)
* `Windows Credential Locker
  <https://docs.microsoft.com/en-us/windows/uwp/security/credential-locker>`_

Other keyring implementations are available through `Third-Party Backends`_.

Installation - Linux
====================

On Linux, the KWallet backend relies on dbus-python_, which does not always
install correctly when using pip (compilation is needed). For best results,
install dbus-python as a system package.

.. _dbus-python: https://gitlab.freedesktop.org/dbus/dbus-python

Compatibility - macOS
=====================

macOS keychain supports macOS 11 (Big Sur) and later requires Python 3.8.7
or later with the "universal2" binary. See
`#525 <https://github.com/jaraco/keyring/issues/525>`_ for details.

Using Keyring
=============

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'

Command-line Utility
--------------------

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 usage information, invoke with no arguments
or with ``--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

Tab Completion
--------------

If installed via a package manager (apt, pacman, nix, homebrew, etc),
these shell completions may already have been distributed with the package
(no action required).

Keyring provides tab completion if the ``completion`` extra is installed::

    $ pip install 'keyring[completion]'

Then, generate shell completions, something like::

    $ keyring --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring
    $ keyring --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring
    $ keyring --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh

**Note**: the path of `/usr/share` is mainly for GNU/Linux. For other OSs,
consider:

- macOS (Homebrew x86): /usr/local/share
- macOS (Homebrew ARM): /opt/homebrew/share
- Android (Termux): /data/data/com.termux/files/usr/share
- Windows (mingw64 of msys2): /mingw64/share
- ...

After installing the shell completions, enable them following your shell's
recommended instructions. e.g.:

- bash: install `bash-completion <https://github.com/scop/bash-completion>`_,
  and ensure ``. /usr/share/bash-completion/bash_completion`` in ``~/.bashrc``.
- zsh: ensure ``autoload -Uz compinit && compinit`` appears in ``~/.zshrc``,
  then ``grep -w keyring ~/.zcompdump`` to verify keyring appears, indicating
  it was installed correctly.

Configuring
===========

The python keyring lib contains implementations for several backends. The
library will attempt to
automatically choose the most suitable backend for the current
environment. Users may also specify the preferred keyring in a
config file or by calling the ``set_keyring()`` function.

Config file path
----------------

The configuration is stored in a file named "keyringrc.cfg"
found in a platform-specific location. To determine
where the config file is stored, run ``keyring diagnose``.

Config file content
-------------------

To specify a keyring backend, set the **default-keyring** option to the
full path of the class for that backend, such as
``keyring.backends.macOS.Keyring``.

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 ``simplekeyring`` module in
the ``./demo`` directory (not implemented)::

    [backend]
    default-keyring=simplekeyring.SimpleKeyring
    keyring-path=demo

Third-Party Backends
====================

In addition to the backends provided by the core keyring package for
the most common and secure use cases, there
are additional keyring backend implementations available for other
use cases. Simply install them to make them available:

- `keyrings.cryptfile <https://pypi.org/project/keyrings.cryptfile>`_
  - Encrypted text file storage.
- `keyrings.alt <https://pypi.org/project/keyrings.alt>`_ - "alternate",
  possibly-insecure backends, originally part of the core package, but
  available for opt-in.
- `gsheet-keyring <https://pypi.org/project/gsheet-keyring>`_
  - a backend that stores secrets in a Google Sheet. For use with
  `ipython-secrets <https://pypi.org/project/ipython-secrets>`_.
- `bitwarden-keyring <https://pypi.org/project/bitwarden-keyring/>`_
  - a backend that stores secrets in the `BitWarden <https://bitwarden.com/>`_
  password manager.
- `onepassword-keyring <https://pypi.org/project/onepassword-keyring/>`_
  - a backend that stores secrets in the `1Password <https://1password.com/>`_ password manager.
- `sagecipher <https://pypi.org/project/sagecipher>`_ - an encryption
  backend which uses the ssh agent protocol's signature operation to
  derive the cipher key.
- `keyrings.osx_keychain_keys <https://pypi.org/project/keyrings.osx-keychain-keys>`_
  - OSX keychain key-management, for private, public, and symmetric keys.
- `keyring_pass.PasswordStoreBackend <https://github.com/nazarewk/keyring_pass>`_
   - Password Store (pass) backend for python's keyring 
- `keyring_jeepney <https://pypi.org/project/keyring_jeepney>`__ - a
  pure Python backend using the secret service DBus API for desktop
  Linux (requires ``keyring<24``).


Write your own keyring backend
==============================

The interface for the backend is defined by ``keyring.backend.KeyringBackend``.
Every backend should derive from that base class and define a ``priority``
attribute and three functions: ``get_password()``, ``set_password()``, and
``delete_password()``. The ``get_credential()`` function may be defined if
desired.

See the ``backend`` module for more detail on the interface of this class.

Keyring employs entry points to allow any third-party package to implement
backends without any modification to the keyring itself. Those interested in
creating new backends are encouraged to create new, third-party packages
in the ``keyrings`` namespace, in a manner modeled by the `keyrings.alt
package <https://github.com/jaraco/keyrings.alt>`_. See the
``setup.cfg`` file
in that project for hints on how to create the requisite entry points.
Backends that prove essential may be considered for inclusion in the core
library, although the ease of installing these third-party packages should
mean that extensions may be readily available.

To create an extension for Keyring, please submit a pull request to
have your extension mentioned as an available extension.

Runtime Configuration
=====================

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.

To invoke ``set_keyring``::

    # define a new keyring class which extends the KeyringBackend
    import keyring.backend

    class TestKeyring(keyring.backend.KeyringBackend):
        """A test keyring which always outputs the 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):
            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 successfully")
    except keyring.errors.PasswordSetError: