Free Space in the Local Docker Registry

You can delete images and perform garbage collection to free unused registry space on the docker-distribution file system of the controllers.

About this task

Simply deleting an image from the local Docker registry does not free the associated space from the file system. To do so, you must also run the registry-garbage-collect command.


  1. Identify the name of the image you want to delete.

    ~(keystone_admin)]$ system registry-image-list
    | Image Name                                           |
    |               |
    | |
    |                           |
    |                        |
    |                                   |
    |                                      |
    |                            |
    |                   |
    |                                |
    |                            |
    |                                     |
    |                             |
    |                                   |
    |                      |
    |                                  |
  2. Find tags associated with the image.

    ~(keystone_admin)]$ system registry-image-tags <imageName>
  3. Free file system space.

    ~(keystone_admin)]$ system registry-image-delete <imageName>:<tagName>

    This step only removes the registry’s reference to the image:tag.


    Do not delete image:tags that are currently being used by the system. Deleting both the local Docker registry’s image:tags and the image:tags from the Docker cache will prevent failed deployment pods from recovering. If this happens, you will need to manually download the deleted image from the same source and push it back into the local Docker registry under the same name and tag.

    If you need to free space consumed by stx-openstack images, you can delete older tagged versions.

  4. Free up file system space associated with the deleted/unreferenced images.

    The registry-garbage-collect command removes unreferenced image:tags from the file system and frees the file system spaces allocated to deleted/unreferenced images.

    ~(keystone_admin)]$ system registry-garbage-collect
    Running docker registry garbage collect


    In rare cases the system may trigger a swact during garbage collection, and the registry may be left in read-only mode. If this happens, run registry-garbage-collect again to take the registry out of read-only mode.