Cleq designs, builds, and manages secure, scalable cloud infrastructure with expert support.
© 2026 Cleq OÜ. All rights reserved.
Working with Local Docker Images and Google Container Registry Think of GCR as a cloud storage space for your Docker images. Instead of keeping images only on your computer, you can upload them to GCR and access them from anywhere.
Google Container Registry (GCR) is a service that stores and manages Docker container images in the cloud. This guide will show you how to push (upload) and pull (download) Docker images to and from Google Container Registry.
Think of GCR as a cloud storage space for your Docker images. Instead of keeping images only on your computer, you can upload them to GCR and access them from anywhere.
Before you begin, make sure you have:
Google Cloud Account - An active account with proper permissionsDocker Installed - Docker running on your computerGoogle Cloud SDK - The gcloud command-line tool installedGCP Project - A Google Cloud project created and ready
The Google Cloud SDK provides tools to interact with Google Cloud services. You need to configure it first.
Open your terminal and run:
$ gcloud init
This command will:
Ask you to log in to your Google Cloud account
Let you choose which project to use
Set up default settings for your commands
Important : Make sure you select the correct project because your images will be stored in that project.
After setup, verify your settings:
$ gcloud config list
This shows your current account, project, and other settings.
For Docker to communicate with Google Container Registry, you need to set up authentication.
Run this command:
$ gcloud auth configure-docker
When asked for confirmation, type Y and press Enter.
This command tells Docker to use your Google Cloud credentials when connecting to GCR. It creates or modifies a file at ~/.docker/config.json that stores this authentication information.
Check if the configuration file was created:
$ cat ~/.docker/config.json
You should see Google Container Registry endpoints listed in the file.
Once authenticated, you can see what images are stored in your registry.
To see all images in your project:
$ gcloud container images list
This displays images in the format: HOSTNAME/PROJECT-ID/IMAGE-NAME
To see all versions (tags) of a specific image:
$ gcloud container images list-tags gcr.io/YOUR_PROJECT_ID/IMAGE_NAME
Tags help you track different versions of the same image (like v1.0, v2.0, latest).
Pulling means downloading an image from GCR to your local computer.
$ docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG
HOSTNAME : The registry location (like gcr.io)PROJECT-ID : Your Google Cloud project IDIMAGE : The name of your imageTAG : The version you want (like latest or v1.0) $ docker pull gcr.io/myproject/nginx:latest
GCR offers different locations for better performance:
gcr.io - Global (multi-region)us.gcr.io - United Stateseu.gcr.io - European Unionasia.gcr.io - Asia Choose the one closest to you for faster downloads.
After pulling, check if the image is on your computer:
You should see your downloaded image in the list.
Pushing means uploading an image from your computer to GCR.
If you haven't built your Docker image yet:
$ docker build -t myimage:tag .
This creates an image from your Dockerfile.
Before pushing, you need to tag your image with the GCR format:
$ docker image tag SOURCE_IMAGE:TAG HOSTNAME/PROJECT-ID/IMAGE:TAG
Let's say you have a local image called nginxlocal:latest:
$ docker image tag nginxlocal:latest gcr.io/myproject/nginx:latest
Takes your local image nginxlocal:latest
Creates a new tag gcr.io/myproject/nginx:latest
Both tags point to the same image (no copying)
Verify the tag was created:
nginxlocal:latest (your original)gcr.io/myproject/nginx:latest (the new tag) They have the same IMAGE ID because they're the same image.
Now push the image to Google Container Registry:
$ docker image push --all-tags gcr.io/myproject/nginx
The --all-tags flag uploads all versions of the image at once.
Progress bars showing upload status
Which image layers are being uploaded
Confirmation when the upload is complete
Docker is smart - if a layer already exists in GCR, it won't upload it again.
Check if your image is now in GCR:
$ gcloud container images list
$ gcloud container images list-tags gcr.io/myproject/nginx
# Initialize gcloud
$ gcloud init
# Configure Docker authentication
$ gcloud auth configure-docker
# List all images
$ gcloud container images list
# List tags for an image
$ gcloud container images list-tags gcr.io/PROJECT-ID/IMAGE
# Pull from GCR
$ docker pull gcr.io/PROJECT-ID/IMAGE:TAG
# View local images
$ docker images
# Build image
$ docker build -t myimage:tag .
# Tag for GCR
$ docker image tag myimage:tag gcr.io/PROJECT-ID/IMAGE:TAG
# Push to GCR
$ docker image push --all-tags gcr.io/PROJECT-ID/IMAGE
Solution : Refresh your login
$ gcloud auth login
$ gcloud auth configure-docker
Solution : Check your account has the right permissions in Google Cloud Console. You need roles like Storage Admin or Storage Object Creator.
Solution : Set the correct project
$ gcloud config set project YOUR_PROJECT_ID
Check your internet connection
Use a regional registry closer to your location
Try again during off-peak hours
Use clear, descriptive names:
Good: gcr.io/myproject/web-api:v1.0.0
Bad: gcr.io/myproject/img1:latest
Use version numbers: v1.0.0, v1.0.1
Use environment tags: dev, staging, prod
Always tag specific versions, don't rely only on latest
Regularly delete old, unused images
Use smaller base images when possible
Remove unnecessary files from your images
Don't store passwords or secrets in images
Scan images for security vulnerabilities
Use private repositories for sensitive applications
Set proper access controls in Google Cloud
Google Container Registry makes it easy to store and share Docker images in the cloud. With these basic commands, you can now manage your container images effectively.
Now you're ready to work with Docker images in Google Container Registry!
Cleq Blog