Easy way to remove a tag from a private Docker registry?

I have a private Docker registry, v2.6.0, containing several tagged versions on an image:

foo/bar:1_keep    (same image as 1)
foo/bar:latest    (same image as 3)

I want to remove a single tag without necessarily removing the image. So if I remove tag 2, it's okay to remove the image because nothing else refers to it. But if I remove tag 1, only that tag should go, not the image.

That suggests an API request like this:

DELETE http://repo/v2/foo/bar/tags/1

But that gives me a 404. Instead I have to delete the manifest, which means doing all the work of checking that it isn't in use by another tag.

I looked at the source of https://github.com/fraunhoferfokus/deckschrubber and it doesn't appear to trouble itself with checking that it's safe to remove a manuscript. Am I missing something?

Is there a better way of doing this? If not, why not, and is it likely to be fixed?

There is currently no api to delete a specific tag. Theoretically you could push a new (possibly empty) manifest to an existing tag, and then delete that. Otherwise, you'll want to track all tags and manifests in your cleanup routine to identify what is safe to delete.


Tag deletion was added to the now 1.0 OCI distribution-spec. With that, pull request (#3427) was approved to distribution/distribution which is the upstream for the registry image. Its got a milestone of the 3.0 release, so this may be a feature that gets added in the future.

I've also been working on regclient which implements both the tag delete API, and falls back to pushing an empty manifest and deleting that. For a CLI, regclient includes regctl which would look like:

regctl tag rm registry:5000/repo:tag