Delete DockerHub images

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 to deprecate old versions.
  • Use Docker Registry HTTP API V2 to remove tags from a remote registry like Docker Hub.

Note: If instead of a remote registry like Docker Hub you need to remove images from a Docker installation we have a post called “How to purge Docker images, containers, networks or volumes” that explains how to do it.

Remove tag from Docker Hub registry

Remove image/tag from Docker Hub using its API

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"

login_data() {
cat <<EOF
{
  "username": "$USERNAME",
  "password": "$PASSWORD"
}
EOF
}

TOKEN=`curl -s -H "Content-Type: application/json" -X POST -d "$(login_data)" "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 image/tag 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_1:tag_1 org/image_2: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.17-alpine          aaad4724567b

And remove the Docker image by name/repo and tag:

# docker remove image:tag
$ docker rmi {image}:{tag}

# docker remove nginx image with tag 1.17-alpine
$ docker rmi nginx:1.17-alpine

Note: If you try to remove images by repo/name without specifying a tag, Docker will perform the deletion of the image using the tag latest.

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

$ docker rmi {image_id}

# example
$ docker rmi aaad4724567b

Finally, you should definitely take a look at these books to fuel your Docker knowledge: