Remove docker image in registry by removing files/folders on server

I have the following problem with deleting an image or tag in docker-registry v2:

I have a server that runs a docker-registry. I created an image and pushed it, that I now want to be gone. Now I want to remove the image (or at least the tag, if image impossible).

The current frontend version doesn't support such a functionality.

I tried it via a curl -u MY_USERNAME -X DELETE MY_DOMAIN:PORT/v2/IMAGE_NAME/manifests/REFERENCE command, like the HTTP API reference states, and entered the password, but the execution resulted in an empty line, no authentication error (authentication is activated) or success message. The tag is still available.

Since I have access to the server, I came up with the following idea: Can I simply and savely just remove the folder v2/repositories/IMAGE_NAME/_manifests/tags/VERSION (or another file/folder)? Or does that result in a break of the registry? What initial steps, like stop the registry service, do I have to do?

Yea they didn't make this easy and it's still not perfect, but the v2 registry API now has the ability to delete images.

Can I simply and savely just remove the folder v2/repositories/IMAGE_NAME/_manifests/tags/VERSION

The actual image data is stored in the blobs directory on disk but they are shared between different manifests so it's not safe to just purge that directory out unless you've considered all images that may share the blobs.

Here is the method to delete an image using the v2 docker API:

Firstly, your registry has to have DELETE enabled. Either set the env var:


or in the config.yml have to set

    enabled: true

Next, run the deletion via API calls (You can easily test via Postman or just using curl/etc)

NOTE: In the below calls, add "Accept: application/vnd.docker.distribution.manifest.v2+json" to the HTTP Header

  1. Gather image digest:

    HEAD https://myprivateregistry:5001/v2/<image_name>/manifests/<image_tag>

    This call returns the header key Docker-Content-Digest with a value like this: sha256:b57z31xyz0f616e65f106b424f4ef29185fbd80833255d79dabc73b8eb873bd

  2. Using that value from step 2, run the DELETE http call:

    DELETE https://myprivateregistry:5001/v2/<image_name>/manifests/sha256:b57z31xyz0f616e65f106b424f4ef29185fbd80833255d79dabc73b8eb873bd

    API returns 202 Accepted

  3. Run garbage collection manually if you don't want to wait for its next scheduled run: registry garbage-collect /etc/docker/registry/config.yml

    Example if running registry as a container: docker exec -t registry-test ./bin/registry garbage-collect /etc/docker/registry/config.yml

    Garbage collector deletes the associated blobs and manifests from disk for you.

At this point the image:tag is completely deleted from disk and is purged from the registry. The blobs are deleted and you'll see the manifests gone from v2/repositories/<image_name>/_manifests

NOTE: If this was the last image in your repo, you still have to manually delete the repo listing from disk (v2/repositories/<image_name>/_layers) - however this is just metadata. The actual image data has already been removed. I believe this might be a bug in the garbage collector. I have a question about it here: Docker Private Registry - Deleted all images, but still showing in catalog