docker-credential-gcr is Google Container Registry‘s standalone,
gcloud SDK-independent Docker credential helper. It allows for v18.03+ Docker clients to easily make authenticated requests to GCR’s repositories (gcr.io, eu.gcr.io, etc.).
docker-credential-gcr is primarily intended for users wishing to authenticate with GCR in the absence of
gcloud, though they are not mutually exclusive. For normal development setups, users are encouraged to use
gcloud auth configure-docker, instead.
The helper implements the Docker Credential Store API, but enables more advanced authentication schemes for GCR's users. In particular, it respects Application Default Credentials and is capable of generating credentials automatically (without an explicit login operation) when running in App Engine or Compute Engine.
For even more authentication options, see GCR's documentation on advanced authentication methods.
By default, the helper searches for GCR credentials in the following order:
Users may limit, re-order how the helper searches for GCR credentials using
docker-credential-gcr config --token-source. Number 1 above is designated by
store and 2-5 by
env (which cannot be individually restricted or re-ordered). Multiple sources are separated by commas, and the default is
While it is recommended to use
gcloud auth configure-docker in
gcloud-based work flows, you may optionally configure
docker-credential-gcr to use
gcloud as a token source (see example below).
To use only the gcloud SDK's access token:
docker-credential-gcr config --token-source="gcloud"
To search the environment, followed by the private store:
docker-credential-gcr config --token-source="env, store"
To verify that credentials are being returned for a given registry, e.g. for
echo "https://gcr.io" | docker-credential-gcr get
As of the 2.0 release,
docker-credential-gcr no longer supports generalized
The program in this repository is written with the Go programming language and built with
make. These instructions assume that Go 1.11+ and
make are installed on a *nix system.
You can download the source code, compile the binary, and put it in your
go get -u github.com/GoogleCloudPlatform/docker-credential-gcr
$GOPATH/bin is in your system
$PATH, this will also automatically install the compiled binary. You can confirm using
which docker-credential-gcr and continue to the section on Configuration and Usage.
Alternatively, you can use
make to build the program. The executable will be output to the
bin directory inside the repository.
cd $GOPATH/src/github.com/GoogleCloudPlatform/docker-credential-gcr make
Then, you can put that binary in your
$PATH to make it visible to
docker. For example, if
/usr/bin is present in your system path:
sudo mv ./bin/docker-credential-gcr /usr/bin/docker-credential-gcr
Configure the Docker CLI to use
docker-credential-gcr as a credential helper for the default set of GCR registries:
To speed up
docker builds, you can instead configure a minimal set of registries:
docker-credential-gcr configure-docker --registries="eu.gcr.io, marketplace.gcr.io"
Log in to GCR (or don't! See the GCR Credentials section)
docker pull gcr.io/project-id/neato-container
Log out from GCR
credHelpers entry in the Docker config file (usually
~/.docker/config.json on OSX and Linux,
%USERPROFILE%\.docker\config.json on Windows) for each GCR registry that you care about. The key should be the domain of the registry (without the “https://”) and the value should be the suffix of the credential helper binary (everything after “docker-credential-”).
e.g. for `docker-credential-gcr`:
Apache 2.0. See LICENSE for more information.