keyring-rs: one API over the native secret stores

The v1 feature keeps the previous API intact

The keyring crate describes itself as a simple wrapper library for the Rust keyring ecosystem. If you link it with the default feature, named v1, your application gains the ability to set, get and delete both plain-text and binary secrets in the native secure stores on Mac, Windows and *nix operating systems, using exactly the same API as the original v1 version of the crate did.

That last clause is the migration story in a single sentence. The crate has a long history, first written by Walther Chen as an API library plus credential store combination, and it is now maintained by Dan Brotsky. The API and library parts have been moved into the keyring-core crate and the credential stores into separate crates of their own, and the v1 feature exists so that existing code keeps working.

The default feature set is small and deliberate. From the crate manifest, v1 pulls in three stores: apple-native-keyring-store with the keychain feature, windows-native-keyring-store, and zbus-secret-service-keyring-store. One native store per desktop platform family, no more.

The crate manifest also sets a floor worth noting: edition 2024 and rust-version 1.88.0. The dependency set is small too, with keyring-core 1.0.0 as the only runtime dependency in the manifest shown, and the heavier store crates pulled in per target, such as db-keystore only for 64-bit targets that are not iOS or Android.

Why the ecosystem was split into separate store crates

The split is the most consequential design decision in the project, and the README explains it in operational terms.

The advice for developers who want the full power of the ecosystem is not to link directly against this crate using the cli feature, because that brings with it a host of credential stores and other libraries they do not need. Instead, they should take dependencies on the keyring-core crate and the specific credential stores they want to use, and then copy any of the code in the cli module that they find useful for instantiating and accessing those stores.

So the cli module serves two audiences at once. For the maintainers it is a catalogue of sample code, and it is described as well maintained and comprehensive sample Rust code for developers looking to use the full power of the ecosystem. For applications it is a source of patterns to copy rather than a dependency to declare.

The cli feature in the manifest shows what that catalogue contains. Alongside the stores already used by v1 it adds android-native-keyring-store, apple-native-keyring-store with the protected feature, db-keystore, dbus-secret-service-keyring-store, keyring-core with its sample store, and linux-keyutils-keyring-store.

The historical reason for the split is stated too: separating the API from the stores gives developers of keyring-using applications a lot more control over exactly what credential stores to use on which platforms.

The keyring-cli binary and what it is for

Building the keyring-cli example app produces a command line interface for issuing one keyring call at a time and examining its results. The usage information comes from:

keyring-cli --help

The framing of one call at a time is the important detail. This is an inspection and debugging tool, a way to poke at a store and see what comes back, and the sample code inside the cli module doubles as the documentation for how to drive each store from Rust.

The repository carries several example applications beyond that one, and each has a distinct purpose. The unit-test app runs unit tests against all the credential stores available on the platform, is invoked with no arguments, and is available on all platforms that can run command line apps. The README singles it out for contributors: a developer adding a credential store module should run these unit tests against their store once it is integrated.

That is the useful framing for the whole repository. It is not only a library, it is a conformance harness for store implementations, and the example apps are the tests.

The leak test and the native viewer check

Two of the example apps exist to catch specific failure modes in a credential store, and both are worth understanding before you write your own store.

The leak test makes sure that none of the secret data transferred to and from the credential store leaks into heap in dropped data. The README says to read the shell scripts for information about how to use it, and to try it with the keyring-core sample store to see what it looks like when secrets do leak. That last point is a good design: a test that only passes is a test you cannot trust, so the project gives you a store that is supposed to fail so you can see the failure signal.

The set-or-clear-three example is a different kind of check. Almost all the operating systems that provide native secure stores also provide native viewers for seeing the credentials in those stores, and this example creates or deletes three sample applications using the keyring. You then look at the native viewers to see how those credentials appear and disappear, and how they can be manipulated with the native tools. The README frames it as a way to understand how the conventions used by the keyring compare with those used by other tools.

That comparison matters more than it sounds. A keyring entry that is invisible or awkward in the platform's own viewer will be invisible or awkward to the person trying to recover an account on a locked-out laptop.

Scripting: the Python wrapper beats the CLI

The README is unusually blunt about a limitation of its own tool, and the limitation is about the CLI.

The CLI provided by this crate is neither efficient nor convenient for scripting, because each invocation loads a credential store, issues just one command against it, and then outputs the results in a format that is hard to parse. If you are scripting keyring commands, the recommendation is to use the Python wrapper for this crate available on PyPI in the rust-native-keyring project.

It installs with:

pip install rust-native-keyring

and is loaded into a Python session with:

import rust_native_keyring

The sources for that Python module are built using PyO3 and live in a separate repository, the keyring-for-python project. So the scripting story spans three repositories: this crate, the Python binding sources, and the published package.

The reason the CLI loses on this axis is structural rather than incidental. A process that loads a credential store, performs one operation and exits pays the store initialisation cost on every call, and it exposes the result in a human oriented format. A long lived Python process that keeps the store loaded amortises the first cost across many calls, and the wrapper exposes structured data.

If your use case is a script that reads one token at startup, the difference matters.

A cross-platform GUI in beta for phones and desktops

There is a Tauri 2.0 cross-platform GUI for Keyring in a separate repository, the keyring-demo project. It lets you poke around in any of the keyring-compatible credential stores available on your platform.

The status of that GUI is worth stating precisely. It is currently in public beta testing on iOS, macOS and Android, with instructions in the project's issue tracker for iOS and macOS and separately for Android, and it is available for macOS in a non-sandboxed build, for Linux, and for Windows through CrabNebula.

A GUI that can open a store and show you its contents has an obvious role in testing store implementations, which is the same thread running through the example applications. It also has a role for users, since a credential store that cannot be inspected is a credential store that cannot be recovered from.

The desktop GUI and the Rust CLI both come out of this repository's example applications, while the cross-platform GUI is a separate project with its own release channel. That split is worth remembering when you look for a binary: the crabnebula and beta distributions are for the demo GUI, not for the crate itself.

Version history, the Rust floor and dual licensing

The release history is short and tells you what has been changing. v4.1.5 was a compatibility release on 2026-07-14, v4.1.6 on 2026-08-01 fixed a concurrent initialisation bug, and v4.2.0 on 2026-08-29 updated the CLI dependencies. The manifest version is 4.2.0, matching the latest tag.

The concurrent initialisation fix is the one to notice. If your application initialises the keyring from more than one thread, or from several call sites that race, that release is the one that matters, and the fact that it landed as a patch release says the maintainers treat it as a defect rather than a feature.

The Rust toolchain floor is 1.88.0, and the edition is 2024, so a project pinned to an older Rust will need to deal with that before anything else.

Licensing is permissive and dual. The crate is licensed under either the Apache License, Version 2.0 or the MIT licence at your option, with LICENSE-APACHE and LICENSE-MIT files in the repository root, and contributions are dual licensed the same way unless a contributor states otherwise. For a library that ends up inside a proprietary application, either choice is workable, and the choice matters mostly for how you want to handle patent grants and for how you phrase your own notice file.

The Contributors.md file records a long list of contributors across the generations of the crate, which is the kind of history you want in a dependency that many other projects sit on top of.

Editorial conclusion

Use the keyring crate with the default v1 feature when you want the previous API unchanged and a working store on each desktop platform, and use keyring-core plus individual store crates when you need control over which stores ship in a release. Do not enable the cli feature in a shipped application, since the README says it drags in a host of credential stores you do not need, and do not script against the keyring-cli binary, since the project itself points you at the Python wrapper for that. Before you start, confirm your Rust toolchain meets the 1.88.0 floor, decide which credential stores your platforms need, and pin a version such as v4.2.0 because the v4.1.6 release fixed a concurrent initialisation bug.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. open-source-cooperative/keyring-rs on GitHub
4. README
5. Releases