How to completely remove docker images from a Docker registry V2?

In the last few weeks, I have suffered from full storage on our Linux server. Then, I went to check on that server, and I saw 100% of storage had been consumed by the docker registry. Finally, after I spent a few hours of research, I had come up with solutions to deal with it.

In this article, I will show you step-by-step how to delete unused images from a docker registry efficiently.

First of all, you need to clear the manifest or reference of the docker image that you want to delete, and to achieve it you have 2 possibilities; one by using an HTTP endpoint and another one is by clearing manually on a mounted directory on your Linux server. Lastly, you need their internal garbage collection which is the most crucial part of clearing a high disk usage.

To clear the manifest using the HTTP API you need to set REGISTRY_STORAGE_DELETE_ENABLED = true in your docker-compose file and make sure that you are using a registry V2.

version: '3.8'

services:
  registry:
    container_name: docker_registry
    image: registry:latest
    ports:
    - "5000:5000"
    restart: always
    environment:
      REGISTRY_AUTH_HTPASSWD_REALM: Registry
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
    volumes:
      - ./registry:/var/lib/registry

Now re-run the application and try to clear your desired image as following

I am going to use curl to clear the manifest, however, you can also other HTTP tools like Postman. Replace the variables based on your own setup and they are:

1. Username and password to your registry

2. Registry ip

3. Image name

4. Image tag number or version number

curl -v -u "[username]:[pw]" -H "Accept: application/vnd.docker.distribution.manifest.v2+json" -X HEAD https://[registry-ip]/v2/[image-name]/manifests/[image-version or tag number]

After executing this, you will get the following header in the response “Docker-Content-Digest”. Take the value of that header and use the same and use the HTTP DELETE method to delete the manifest.

The value of Docker-Content-Digest looks like this sha256:109a917ddb2b48d5007135ce55705b586a409804746d47735269302a4f8714f0

The endpoint is DELETE /v2/<name>/manifests/<reference>

curl -u "[username]:[pw]" -X DELETE https://[registry-ip]/v2/[image-name]/manifests/[value of Docker-Content-Digest]

Alternatively, you can log in to a server and find a mounted directory of your registry. This comes in handy when you want completely remove all image version from your registry, you can just locate it folder and delete it all. So the path of it looks like this docker/registry/v2/repositories.

Eventually, it’s time to show you an important part and it is how to use a garbage collection to free up server storage.

docker exec [container-name or id ] bin/registry garbage-collect /etc/docker/registry/config.yml

Bing go now, you can check how much you’ve freed up your storage.

Hope you find this article helpful. Thanks for reading.