Purpose

The purpose of this post is to learn how to remove a Docker tag from Docker Hub registry. These are some possible scenarios:

  • Using JenkinsCI or other CI/CD tools to create Docker image snapshots and there’s a need to clean old snapshot tags.
  • Clean old tags in order to deprecate old versions.

Remove a Docker image tag from Docker Hub

To delete a tag from Docker Hub you need and auth token and perform a delete HTTP call to the registry like the following script:

#!/usr/bin/env bash

USERNAME="docker_username"
PASSWORD="docker_password"
ORGANIZATION="organization"
IMAGE="image"
TAG="tag"

TOKEN=`curl -s -H "Content-Type: application/json" -X POST -d '{"username": "'$USERNAME'", "password": "'$PASSWORD'"}' https://hub.docker.com/v2/users/login/ | jq -r .token`

curl 'https://hub.docker.com/v2/repositories/${ORGANIZATION}/${IMAGE}/tags/${TAG}/' \
-X DELETE \
-H "Authorization: JWT ${TOKEN}"

This script can be used with other Docker image repositories based on Docker registry v2.

More info about Docker Registry HTTP API V2 here: https://docs.docker.com/registry/spec/api/

Remove an image from Docker Hub using a Docker image

Update: Lumir Mrkva created a Docker image to easily remove a Docker Hub image tag called Remove dockerhub tags. Thanks Lumir! Syntax:

docker run --rm -it lumir/remove-dockerhub-tag --user user --password pass org/image_name_1:image_tag_1 org/image_name_2:image_tag_2 ...

Bonus track: Remove a local Docker image tag

List your Docker images and/or find a specific tag from your local Docker registry:


docker images

# or a newer version
$ docker image list

# search for a specific docker tag to remove
$ docker image list | grep nginx
nginx                        1.16-alpine          aaad4724567b        6 weeks ago         21.2MB

And remove the Docker image by name and tag:

$ docker rmi {image}:{tag}

# example
$ docker rmi nginx:1.16-alpine

Alternatively, instead of removing the Docker image by name and tag you can also do it by image ID:

$ docker rmi {image_id}

# example
$ docker rmi aaad4724567b