You can delete container images from your container registry.
Deleting a container image on self-managed instances doesn’t free up storage space, it only marks the image as eligible for deletion. To actually delete unreferenced container images and recover storage space, administrators must run garbage collection.
On GitLab.com, the latest version of the container registry includes an automatic online garbage collector. For more information, see this blog post. In this new version of the container registry, the following are automatically scheduled for deletion in 24 hours if left unreferenced:
- Layers that aren’t referenced by any image manifest.
- Image manifests that have no tags and aren’t referenced by another manifest (like multi-architecture images).
The online garbage collector is an instance-wide feature, and applies to all namespaces.
To delete container images using the GitLab UI:
- On the left sidebar, select Search or go to and find your project or group.
- A group, select Operate > Container Registry.
- A project, select Deploy > Container Registry.
From the Container Registry page, you can select what you want to delete, by either:
- Deleting the entire repository, and all the tags it contains, by selecting the red Trash icon.
- Navigating to the repository, and deleting tags individually or in bulk by selecting the red Trash icon next to the tag you want to delete.
- On the dialog, select Remove tag.
You can use the API to automate the process of deleting container images. For more information, see the following endpoints:
- Delete a Registry repository
- Delete an individual Registry repository tag
- Delete Registry repository tags in bulk
The following example defines two stages:
build_image job builds a container
image for the branch, and the
delete_image job deletes it. The
reg executable is downloaded and used to
remove the container image matching the
predefined CI/CD variable.
To use this example, change the
IMAGE_TAG variable to match your needs.
stages: - build - clean build_image: image: docker:20.10.16 stage: build services: - docker:20.10.16-dind variables: IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG only: - branches except: - main delete_image: before_script: - curl --fail --show-error --location "https://github.com/genuinetools/reg/releases/download/v$REG_VERSION/reg-linux-amd64" --output ./reg - echo "$REG_SHA256 ./reg" | sha256sum -c - - chmod a+x ./reg image: curlimages/curl:7.86.0 script: - ./reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG stage: clean variables: IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 REG_VERSION: 0.16.1 only: - branches except: - main
You can create a per-project cleanup policy to ensure older tags and images are regularly removed from the container registry.