• Use the GitLab UI
• Use the GitLab API
• Use GitLab CI/CD
• Use a cleanup policy

Delete container images from the Container Registry

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. The automatic online garbage collector is an instance-wide feature, rolling out gradually to a subset of the user base. Some new container image repositories created from GitLab 14.5 onward are served by this new version of the Container Registry. In this new version of the Container Registry, layers that aren’t referenced by any image manifest, and image manifests that have no tags and aren’t referenced by another manifest (such as multi-architecture images), are automatically scheduled for deletion after 24 hours if left unreferenced.

Use the GitLab UI

To delete container images using the GitLab UI:

1. On the top bar, select Main menu, and:
   • For a project, select Projects and find your project.
   • For a group, select Groups and find your group.
2. On the left sidebar, select Packages and registries > Container Registry.

3. 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.
4. In the dialog box, select Remove tag.

Use the GitLab API

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

Use GitLab CI/CD

The following example defines two stages: build, and clean. The 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 $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG 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

Use a cleanup policy

You can create a per-project cleanup policy to ensure older tags and images are regularly removed from the Container Registry.