Registry Authentication

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 cargo:token provider is used if no providers are configured.

Cargo also includes platform-specific providers that use the operating system to securely store tokens. The 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 $CARGO_HOME/config.toml which defaults to:

  • Windows: %USERPROFILE%\.cargo\config.toml
  • Unix: ~/.cargo/config.toml

This recommended configuration uses the operating system provider, with a fallback to cargo:token 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.

macOS configuration

# ~/.cargo/config.toml
global-credential-providers = ["cargo:token", "cargo:macos-keychain"]

Linux (libsecret) configuration

# ~/.cargo/config.toml
global-credential-providers = ["cargo:token", "cargo:libsecret"]

Windows configuration

# %USERPROFILE%\.cargo\config.toml
global-credential-providers = ["cargo:token", "cargo:wincred"]

See for more details.

Built-in providers

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.

cargo:token-from-stdout <command> <args>

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 login and cargo logout are not supported and return an error if used.

The following environment variables will be provided to the executed command:

  • CARGO — Path to the cargo binary 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.

Credential plugins

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 PATH).

For example, to install cargo-credential-1password from do the following:

Install the provider with cargo install cargo-credential-1password

In the config, add to (or create)

global-credential-providers = ["cargo:token", "cargo-credential-1password --email"]

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 the [credential-alias] table.