Introduction

Deleting images from a private Docker registry is usually a manifest-management task followed by storage cleanup, not just a tag removal. In a Docker Distribution-style registry, the normal workflow is to resolve the tag to a manifest digest, delete that manifest, and then run garbage collection if you want unreferenced blobs reclaimed.

Understand What Actually Gets Deleted

A tag points to a manifest, and the manifest points to one or more layer blobs. Deleting one part does not automatically mean everything underneath disappears immediately.

That means:

• deleting a tag reference may not free much disk space
• layer blobs can still be shared by other images
• deleting by manifest digest is more precise than deleting by guesswork

This is why registry cleanup should be treated as lifecycle management, not as a casual file delete.

Make Sure Deletion Is Enabled

For Docker Distribution, delete support must be enabled in the registry configuration.

1version: 0.1
2storage:
3  filesystem:
4    rootdirectory: /var/lib/registry
5delete:
6  enabled: true

If deletion is disabled, a correct DELETE request can still fail. After changing the configuration, restart the registry so the setting takes effect.

Discover Repositories and Tags First

Inspect the registry state before deleting anything.

curl -s https://registry.example.com/v2/_catalog
curl -s https://registry.example.com/v2/myapp/tags/list

If authentication is required:

curl -u "user:password" -s https://registry.example.com/v2/myapp/tags/list

Always verify the exact repository and tag names. Mistakes usually come from targeting the wrong path, not from misunderstanding the DELETE syntax.

Resolve the Tag to a Manifest Digest

Docker Distribution deletes by manifest digest, not usually by the human-friendly tag name. Request the manifest headers and inspect the Docker-Content-Digest value.

curl -I \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  https://registry.example.com/v2/myapp/manifests/1.4.2

The returned digest is the real deletion target.

Delete the Manifest

Once you have the digest, send the DELETE request.

curl -X DELETE \
  https://registry.example.com/v2/myapp/manifests/sha256:abcd1234ef5678...

Then confirm the tag no longer appears:

curl -s https://registry.example.com/v2/myapp/tags/list

Some registry UIs cache their views, so trust the API and registry logs more than a dashboard that refreshes slowly.

Run Garbage Collection if You Need Disk Space Back

Deleting the manifest usually does not reclaim all storage immediately. Garbage collection removes unreferenced blobs.

docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

This should be treated as an operational change. Running garbage collection while active pushes are happening can be risky depending on how the registry is deployed. In production, it is worth treating garbage collection like a maintenance action with timing, monitoring, and a rollback plan.

Verify Both API State and Storage State

After cleanup, validate both the logical and physical result.

curl -s https://registry.example.com/v2/_catalog
df -h

If disk usage does not change, the usual reason is shared layers or skipped garbage collection, not a mysterious failed delete.

Common Pitfalls

The biggest mistake is deleting a tag and expecting immediate disk reclamation without garbage collection.

Another issue is deleting by guesswork instead of resolving the exact manifest digest first.

A third problem is forgetting that other tags or repositories may still reference shared layers.

Summary

• Private registry image deletion usually means deleting a manifest by digest.
• Ensure delete support is enabled in the registry configuration.
• Discover tags first, then resolve the exact digest before deleting.
• Run garbage collection if reclaiming storage matters.
• Verify both registry API results and actual disk usage after cleanup.