Clean Up Your Docker Registry

Delete unused digests of docker images and save space

Mahesh Chinthaka
Jun 28, 2018 · 3 min read
cleaning docker registry

If you’re using your docker registry to push continuous updates you’ve probably noticed that the disk mount space for the registry is gradually growing.

It looks like it’s time to have a registry clean up. Here’s how to do it.

First, Let’s Get Familiar With the Jargon

One docker image can have multiple tags. Each image has a digest, which is a unique value. When you do continuous pushes (with updated content) to the same image in the registry, the image in the registry will end up with multiple digests.

A tag is composed of several layers. The list of the layers for that particular digest is called a manifest. There is a corresponding blob for each layer. There can also be layers which are not used by any of the tags — those are called abandoned or unused layers. Those corresponding blobs are also unused. We can delete them to gain some space on the disk.

images, tags, layers, and blobs

As you can see, the layers are shared among manifests (tags) — each manifest maintains a reference to the layer. As long as a layer is referenced by one manifest, it cannot be garbage collected.

Digests of a docker repo can be found under RepoDigests after a docker inspect command.

eg : docker inspect


Garbage Collector

The garbage collector is the one who actually deletes unused/abandoned/orphaned blobs.

Garbage collection is the process of removing blobs from the filesystem when they are no longer referenced by a manifest. Blobs can include both layers and manifests.

In order for garbage collector to delete the blobs, we need to make those blobs orphaned. We can achieve that with two methods.

  1. Using v2 registry REST API
  2. Manually deleting in filesystem using ‘rm’ command.

Method 01: Using registry REST API

For this, you need to know the docker image name and the digest you want to delete.

Invoke rest API

eg : curl -vk -X DELETE

You should get a 202 Accepted for a successful invocation.

Then run garbage collector

registry — registry container name.

Method 02: Deleting in the file system

You need to delete two dirs.

rm -r <root>/v2/repositories/${name}/_manifests/revisions/sha256/${hash}

Here <root> means the the registry mount location where this registry container stores all the data in the file system.

eg : /var/lib/registry/docker/registry

If you have mounted this to one of your disks in host machine you can delete from there. Otherwise you will have to attach to the registry container by using docker attach command and delete directories.

Then run garbage collector:

Please note that when using Method 01, registry container should have


You can also pass that as a environmental variable with -e tag when starting the container or inside your dockerfile.

If you are using Method 02, at the time of deleting those dirs the docker registry should be in read-only mode. Nobody should push to registry.

Better Programming

Advice for programmers.

Mahesh Chinthaka

Written by

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade