Cargo authenticates to registries with credential providers. These credential providers are external executables or built-in providers that Cargo uses to store and retrieve credentials.
Using alternative registries with authentication requires a credential provider to be configured
to avoid unknowingly storing unencrypted credentials on disk. For historical reasons, public
(non-authenticated) registries do not require credential provider configuration, and the
provider is used if no providers are configured.
Cargo also includes platform-specific providers that use the operating system to securely store
cargo:token provider is also included which stores credentials in unencrypted plain
text in the credentials file.
It’s recommended to configure a global credential provider list in
which defaults to:
This recommended configuration uses the operating system provider, with a fallback to
to look in Cargo’s credentials file or environment variables.
Some private registries may also recommend a registry-specific credential-provider. Check your registry’s documentation to see if this is the case.
# ~/.cargo/config.toml [registry] global-credential-providers = ["cargo:token", "cargo:macos-keychain"]
# ~/.cargo/config.toml [registry] global-credential-providers = ["cargo:token", "cargo:libsecret"]
# %USERPROFILE%\.cargo\config.toml [registry] global-credential-providers = ["cargo:token", "cargo:wincred"]
for more details.
Cargo includes several built-in credential providers. The available built-in providers may change in future Cargo releases (though there are currently no plans to do so).
Uses Cargo’s credentials file to store tokens unencrypted in plain text.
When retrieving tokens, checks the
CARGO_REGISTRIES_<NAME>_TOKEN environment variable.
If this credential provider is not listed, then the
*_TOKEN environment variables will not work.
Uses the Windows Credential Manager to store tokens.
The credentials are stored as
cargo-registry:<index-url> in the Credential Manager
under “Windows Credentials”.
Uses the macOS Keychain to store tokens.
The Keychain Access app can be used to view stored tokens.
Uses libsecret to store tokens.
On GNOME, credentials can be viewed using GNOME Keyring applications.
Launch a subprocess that returns a token on stdout. Newlines will be trimmed.
- The process inherits the user’s stdin and stderr.
- It should exit 0 on success, and nonzero on error.
cargo logoutare not supported and return an error if used.
The following environment variables will be provided to the executed command:
CARGO— Path to the
cargobinary executing the command.
CARGO_REGISTRY_INDEX_URL— The URL of the registry index.
CARGO_REGISTRY_NAME_OPT— Optional name of the registry. Should not be used as a lookup key.
Arguments will be passed on to the subcommand.
For credential provider plugins that follow Cargo’s credential provider protocol,
the configuration value should be a string with the path to the executable (or the executable name if on the
For example, to install cargo-credential-1password from crates.io do the following:
Install the provider with
cargo install cargo-credential-1password
In the config, add to (or create)
[registry] global-credential-providers = ["cargo:token", "cargo-credential-1password --email email@example.com"]
The values in
global-credential-providers are split on spaces into path and command-line arguments. To
define a global credential provider where the path or arguments contain spaces, use