How to check if a Docker image already exists?

Hello World!

Excited to share my first-ever blog here. This is about how you can check if a docker image (with a specific tag) already exists or not.

We'll divide this article into two parts (based on Types of Images):

Public Images
Private Docker Hub Images

Let's start.

1. Public Images

As we know this is the URL of Docker Hub. https://hub.docker.com

Like every other application, Docker Hub also gives us an API to fetch some details. for our use case the endpoint is:

https://hub.docker.com/v2/repositories/$YourRepoName/tags/$YourTag

When you hit the above Endpoint with the appropriate Repo name and Tag and we get a response like below:

{
  "creator": 7313837,
  "id": 120961274,
  "image_id": null,
  "images": [
    {
      "architecture": "amd64",
      "features": "",
      "variant": null,
      "digest": "sha256:42cdec39185034eb978e30633fc724295cc1f8c5e56c72d14d2c22279ce05fe3",
      "os": "linux",
      "os_features": "",
      "os_version": null,
      "size": 566752686,
      "status": "active",
      "last_pulled": "2021-05-16T23:18:11.632024Z",
      "last_pushed": "2020-10-12T01:39:07.219803Z"
    }
  ],
  "last_updated": "2020-10-12T01:39:07.219803Z",
  "last_updater": 7313837,
  "last_updater_username": "k4kratik",
  "name": "latest",
  "repository": 10006849,
  "full_size": 566752686,
  "v2": true,
  "tag_status": "active",
  "tag_last_pulled": "2021-05-16T23:18:11.632024Z",
  "tag_last_pushed": "2020-10-12T01:39:07.219803Z"
}

👨‍💻 Tip - There are official Docker images that do not require us to put a username while pulling those images, for Example - ubuntu, Postgres, etc.

For example, The link of one of my Repo: hub.docker.com/r/k4kratik/chromedriver-sele..
The link to the official Ubuntu repo is: hub.docker.com/_/ubuntu

ℹ️Notice is the _ here (instead of username)

https://hub.docker.com/v2/repositories/_/ubuntu/tags/latest

So If you use _ in API you will get an error.

🤔 Then what should we use for public images?
The answer is: use library at the place of the username in the API. Like below:

https://hub.docker.com/v2/repositories/library/ubuntu/tags/latest

2. Private Docker Hub Images

Now Comes the Complex Part, As you can assume, We need to authenticate ourselves first before making any request for private repositories.

Let's find out How do we do that?

To Authorize yourself for your private repos on Docker Hub, first, you need to login to Docker Hub programmatically(using API) and it will give you a JWT token. Now use this fresh token in the above-discussed API.

The below command will give you the token

export DOCKER_HUB_USERNAME="my_docker_hub_username"
export DOCKER_HUB_PASSWORD="docker_hub_access_token" 
# You can use your password here but for security purposes, I'll recommend you to use token only
DHUB_TOKEN=$(curl -sSLd "username=${DOCKER_HUB_USERNAME}&password=${DOCKER_HUB_PASSWORD}" https://hub.docker.com/v2/users/login | jq -r ".token")

ℹ️ If you don't know How you can generate a token, check this.

Now we can hit our Previous API with little changes, we will pass our token as Authorization header. In Action: (continuing the above commands)

export DOCKER_REPO="my_username/my_repo_name"
export DOCKER_TAG="v1.2.1"
curl -sH "Authorization: JWT $DHUB_TOKEN" "https://hub.docker.com/v2/repositories/${DOCKER_REPO}/tags/${DOCKER_TAG}/"

This will give you the details about the existence of your specified image.

Sample Output for non-existent image:

{
  "txnid": "REPOSREQ-4d578bda-cc28-4c0d-b2a8-a0634c4e70fe",
  "message": "tag 'v1' not found",
  "errinfo": {
    "api_call_docker_id": "6e1f600164b947b6b69e6266a50a4d40",
    "api_call_name": "GetRepositoryTag",
    "api_call_start": "2021-05-22T08:39:58.506130526Z",
    "api_call_txnid": "REPOSREQ-4d578bda-cc28-4c0d-b2a8-a0634c4e70fe",
    "namespace": "k4kratik",
    "repository": "my-repo",
    "tag": "v1"
  }
}

Sample Output for an image and tag that exist:

{
  "creator": 7313837,
  "id": 118139141,
  "image_id": null,
  "images": [
    {
      "architecture": "amd64",
      "features": "",
      "variant": null,
      "digest": "sha256:0776a3a40c0223f03edaff3f9f20684b71eaa34a64f0ac9285766baced2c392f",
      "os": "linux",
      "os_features": "",
      "os_version": null,
      "size": 44840737,
      "status": "active",
      "last_pulled": "2021-05-16T23:19:04.068998Z",
      "last_pushed": "2020-09-20T15:18:16.510109Z"
    }
  ],
  "last_updated": "2020-09-20T15:18:16.510109Z",
  "last_updater": 7313837,
  "last_updater_username": "k4kratik",
  "name": "latest",
  "repository": 9869685,
  "full_size": 44840737,
  "v2": true,
  "tag_status": "active",
  "tag_last_pulled": "2021-05-16T23:19:04.068998Z",
  "tag_last_pushed": "2020-09-20T15:18:16.510109Z"
}