Untagging removes only the tag and leaves the manifest and layers in the registry. Deleting by tag removes the image behind that tag, along with its other tags and its unique layers. Deleting by digest removes the manifest and every tag that points at it.
Definitions
A manifest describes an image. A tag is a movable name for a manifest. A digest is the content hash that identifies the manifest exactly. One manifest can have zero, one or many tags. The OCI distribution specification defines a manifest digest the same way, noting it may have zero, one or many tags referencing it.
The three operations
| Operation | What goes away | Space freed |
|---|---|---|
| Untag | Only the tag reference | None, the manifest and layers remain |
| Delete by tag | The manifest, all tags on it, and layers unique to it | Unique layers |
| Delete by digest | The manifest, all tags on it, and layers unique to it | Unique layers |
| Delete repository | Every image, tag and unique layer in it | Unique layers |
This table follows the Azure Container Registry documentation, which spells out each case. Other registries use different command names, but the underlying model is the same.
The trap in deleting by tag
Many people read "delete the v2 tag" as "remove one label." Azure's documentation shows a delete by tag of latest that also deleted v3, because both tags pointed at the same manifest. The confirmation prompt lists every image it will remove, and it is worth reading. If you only want to remove a label, untag instead.
This matters for retention too. Harbor notes the same behaviour from the other side: if an artifact has several tags and only some match a retention rule, the artifact and all its tags are retained. Matching is by tag, but action is on the artifact.
Layers are shared
Layers shared by other images are not removed. That is why deleting one image often frees less than people expect, and why space returns later. See why deleting images did not free registry space.
Which one to use
- To retire a label, such as moving a stable tag, untag or retag.
- To remove a bad release entirely, delete by digest after checking what else shares it.
- To clean up a retired project, delete the repository, after confirming nothing deploys from it.
For a vulnerable image, remember that deleting from the registry does not stop running copies. Read does deleting a vulnerable image tag fix the exposure.
Check the permissions
Delete operations are powerful and usually irreversible. Azure states deleted image data is unrecoverable. Limit delete rights to a small set of identities, and use automation with a narrow scope rather than giving every developer delete access. See should you enable delete on a docker registry.
Quick check
Does untagging an image free storage?
No. Per Azure's documentation the manifest and layer data remain; only the tag reference is removed.
If two tags share a digest, does deleting one tag delete both?
In the Azure example, yes, deleting by tag removed the manifest and all tags that referenced it. Read the confirmation prompt first.
Sources
- Delete container images in Azure Container Registry
- OCI distribution specification
- Harbor tag retention rules
Last reviewed: 19 October 2026.
