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.

There is currently a pull request (#2169) to revamp the tag API, including the option to delete tags. It's got a milestone of the 2.7 release, so this may be a feature that gets added in the future.

  • 1
    @emmdee that deletes an image, not a tag. One is the equivalent of a symlink, the other is the equivalent of the file that is being linked to. – BMitch Apr 3 '18 at 19:25
  • Dang you're right, just tested it and it deleted the image alongside all the tags (even though the initial call to get the digest requires a tag). Shame they didn't consider this as a needed function. – emmdee Apr 3 '18 at 19:34
  • @emmdee It's needed functionality, that's why there's a PR. :) – BMitch Apr 3 '18 at 19:51
  • 1
    I've searched around and looks like delete specific tag will not happen any day soon. (maybe never according to github.com/docker/distribution/issues/…) – equivalent8 Oct 16 '19 at 9:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.