---
name: Registry-registry_retention
title: Cleaning up your namespaces in Container Registry
description: You can clean up your namespace by choosing to retain only the most recent images in each repository in that namespace in IBM Cloud® Container Registry.
last-updated: 2026-08-11
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/Registry?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Cleaning up your namespaces in Container Registry
{: #registry_retention}

You can clean up your [namespace](#x2031005){: term} by choosing to retain only the most recent images in each repository in that namespace in IBM Cloud® Container Registry.
{: shortdesc}

You can also choose whether to delete or retain your untagged images.

You can detect and delete old images from all the repositories in a namespace by running a one-off command `ibmcloud cr retention-run`, or by scheduling a policy by running the `ibmcloud cr retention-policy-set` command. You can choose the number of images that you want to keep in each repository in a namespace, all other images are automatically deleted. Both options keep the most recent images. The age of the image is determined by when the image was created, not when it was pushed to the [registry](#x2064940){: term}. The number of images that are kept is the same for each repository in that namespace.

You can also set a deletion threshold to protect recently created images from deletion. When a deletion threshold is set, images that are younger than the specified number of days are always retained, even if keeping them causes the per-repository count to exceed the `--images` value.

The [`ibmcloud cr retention-run`](#retention_images) and [`ibmcloud cr retention-policy-set`](#retention_policy_set) commands produce a list of images to delete. You must confirm that you want to delete those images. After you run the `ibmcloud cr retention-policy-set` command the first time, the policy runs automatically and deletes any images that meet the criteria that are specified in the policy. Deleted images are stored in the trash for 30 days.

If you want to check what's in the trash, run the [`ibmcloud cr trash-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_images_&format=markdown#registry_images_list_trash) command. You can restore images from the trash by running the [`ibmcloud cr image-restore`](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_images_&format=markdown#registry_images_restore) command.

You can't delete images from the trash. Images are stored in the trash for 30 days. You are not billed for any images that are in the trash.
{: note}

If you want to check your policies, you can run the [`ibmcloud cr retention-policy-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_policy_list) command.

If you want to update a policy with new settings, see [Update a retention policy](#retention_policy_update).

If you want to cancel a policy, [update the retention policy so that it keeps all your images](#retention_policy_keep).

You can also clean up your namespace by [deleting your untagged images](#retention_images_untagged).

## Planning retention
{: #retention_plan}

The [`ibmcloud cr retention-run`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_run) and [`ibmcloud cr retention-policy-set`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_policy_set) commands operate on a per-namespace basis. If you have multiple namespaces in your pipeline, you can apply different retention criteria for each namespace to best suit your requirements.

Consider a typical delivery pipeline with development, staging, and production environments. As code is delivered, continuous integration and continuous deployment pushes images into the registry and then deploys them straight to your development environment. After testing, some builds from development are promoted to staging, and then potentially onto production. In this scenario, the rate of image change is fastest in development and slowest in production. If all your environments pull images from the same namespace, it can be difficult to choose an appropriate number of images to retain due to this difference in velocity.

A good approach is to deliver all images into a development namespace, for example `project-development`, and then to use the [`ibmcloud cr image-tag`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_image_tag) command to tag the image into a different namespace when it is promoted to a higher stage of the pipeline. In the previous example, you can have three namespaces: development `project-development`, staging `project-staging`, and production `project-production`. When you are promoting from development to staging, images are tagged from the `project-development` namespace into the `project-staging` namespace, and the images from the `project-staging` namespace are used for deployment. Similarly, when you are promoting from staging to production, images are tagged from the `project-staging` namespace into the `project-production` namespace, and the `project-production` namespace images are used in the production deployment.

You gain the following advantages by using this technique:

- You can choose different retention settings for development, staging, and production namespaces.
- You minimize the chances of accidentally removing an image that might be in use in your staging or production environments, when compared with using a single namespace for all images.
- You can use different [IAM](https://cloud.ibm.com/docs/Registry?topic=Registry-iam&format=markdown) policies. For example, you can have more restrictive access to production images.
- You can sign production images, but development and staging images must remain unsigned.

Some build tools, for example, [Cloud Native Buildpacks](https://buildpacks.io/){: external} and [distroless](https://github.com/GoogleContainerTools/distroless){: external} base images, produce images with the build date set to a specific constant rather than the real build time or with no build timestamp at all. If you want to use retention policies on namespaces that contain images that are built by using similar tools, be aware that images that do not have a created date and images that were created before `2013-01-19T00:13:39Z` are always retained.

For more information, see the following topics for assistance:

- [Why doesn't the retention command show all the images?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-image-list-retention&format=markdown)
- [What are eligible images?](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_faq&format=markdown#faq_eligible_image)

## Clean up your namespaces to keep a set number of images
{: #retention_images}
{: help}
{: support}

Use the `ibmcloud cr retention-run` command to clean up a namespace by retaining a specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted.

You can choose whether to exclude untagged images from the clean-up process. You can also specify a deletion threshold so that recently created images are never deleted.

The [`ibmcloud cr retention-run`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_run) command lists the images to delete and gives you the option to cancel before deletion.

Where an image, within a repository, is referenced by multiple tags, that image is counted only once. Newest images are retained. Age is determined by when the image was created, not when it was pushed to the registry.
{: tip}

The retention command runs against each repository in your namespace. If you have more than one repository in your namespace, the image count after the retention command runs might be higher than the number that you set as the maximum for a repository. For example, if you set your retention command to 500 images per repository, and you have 10 repositories in your namespace, you might have an image count of 5,000.
{: tip}

If you want to restore a deleted image, you can list the contents of the trash by running the [`ibmcloud cr trash-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_trash_list) command and restore a selected image by running the [`ibmcloud cr image-restore`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_image_restore) command.
{: tip}

To reduce the number of images in each repository within your namespace by using the command-line interface (CLI), complete the following steps:

1. Log in to IBM Cloud by running the `ibmcloud login` command.
2. Choose the registry in which you want to clean up your images by running the following command and selecting the appropriate region:

    ```txt
    ibmcloud cr region-set
    ```
    {: pre}

3. To retain the most recent images and delete the others, run one of the following commands:

    - If you want to clean up both tagged and untagged images, run the following command:

        ```txt
        ibmcloud cr retention-run --images IMAGE_COUNT NAMESPACE
        ```
        {: pre}

        Where `IMAGE_COUNT` is the number of images that you want to retain for each repository within your namespace `NAMESPACE`.

    - If you want to clean up tagged images only and retain all untagged images, run the following command:

        ```txt
        ibmcloud cr retention-run --retain-untagged --images IMAGE_COUNT NAMESPACE
        ```
        {: pre}

        Where `IMAGE_COUNT` is the number of images that you want to retain for each repository within your namespace `NAMESPACE`.

    - If you want to protect recently created images from deletion, use the `--deletion-threshold-days` option. Images younger than the specified number of days are always retained, even if they exceed the `--images` count:

        ```txt
        ibmcloud cr retention-run --images IMAGE_COUNT --deletion-threshold-days DAYS NAMESPACE
        ```
        {: pre}

        Where `IMAGE_COUNT` is the number of images to retain, `DAYS` is the minimum age in days before an image can be deleted, and `NAMESPACE` is your namespace.

    If an image that you're expecting to see doesn't show in the list that is produced, see [Why doesn't the retention command show all the images?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-image-list-retention&format=markdown) for assistance.
    {: tip}

4. Verify that the images were deleted by running the following command, and check that the images do not show in the list.

    ```txt
    ibmcloud cr image-list
    ```
    {: pre}

    If the listing images command times out, see [Why is it timing out when I list images?](https://cloud.ibm.com/docs/Registry?topic=Registry-troubleshoot-image-timeout&format=markdown) for assistance.
    {: tip}

## Set a retention policy for your namespaces
{: #retention_policy_set}
{: help}
{: support}

You can set a retention policy for your namespaces to retain only images that meet your criteria. The retention policy runs automatically to clean up your namespaces.

You can choose whether to exclude untagged images from the clean-up process. You can also specify a deletion threshold so that recently created images are never deleted.

You can use the [`ibmcloud cr retention-policy-set`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_policy_set) command to set a policy that retains a specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted and moved to the trash. When you set a policy it runs immediately, then it runs daily. You can set only one policy in each namespace.

Where an image, within a repository, is referenced by multiple tags, that image is counted only once. Newest images are retained. Age is determined by when the image was created, not when it was pushed to the registry.
{: tip}

Retention policies are set per repository in your namespace. If you have more than one repository in your namespace, the image count after the retention policy command runs might be higher than the number that you set as the maximum for a repository. For example, if you set your retention policy to 500 images per repository, and you have 10 repositories in your namespace, you might have an image count of 5,000.
{: tip}

If you delete an image in error, you can restore the image by using the [`ibmcloud cr trash-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_trash_list) and [`ibmcloud cr image-restore`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_image_restore) commands.
{: tip}

To set a policy and immediately move your deleted images to the trash, complete the following steps:

1. Log in to IBM Cloud by running the `ibmcloud login` command.
2. Choose the registry in which you want to clean up your images by running the following command and selecting the appropriate region:

    ```txt
    ibmcloud cr region-set
    ```
    {: pre}

3. To set a policy that retains the most recent images and deletes the others, run one of the following commands:

    - If you want to clean up both tagged and untagged images, run the following command:

        ```txt
        ibmcloud cr retention-policy-set --images IMAGE_COUNT NAMESPACE
        ```
        {: pre}

        Where `IMAGE_COUNT` is the number of images that you want to retain for each repository within your namespace `NAMESPACE`.

        A list of images to delete is displayed.

    - If you want to clean up tagged images only and retain all untagged images, run the following command:

        ```txt
        ibmcloud cr retention-policy-set --retain-untagged --images IMAGE_COUNT NAMESPACE
        ```
        {: pre}

        Where `IMAGE_COUNT` is the number of images that you want to retain for each repository within your namespace `NAMESPACE`.

        A list of images to delete is displayed.

    - If you want to protect recently created images from deletion, use the `--deletion-threshold-days` option. Images younger than the specified number of days are always retained, even if they exceed the `--images` count:

        ```txt
        ibmcloud cr retention-policy-set --images IMAGE_COUNT --deletion-threshold-days DAYS NAMESPACE
        ```
        {: pre}

        Where `IMAGE_COUNT` is the number of images to retain, `DAYS` is the minimum age in days before an image can be deleted, and `NAMESPACE` is your namespace.

        A list of images to delete is displayed.

4. Review the list of images. To run the policy and delete the images, confirm that you want to set the policy.

    If you don't want to delete those images, choose `No`. The policy is not set and the images are not deleted.
    {: tip}

5. Verify that the images were deleted by running the following command, and check that the images appear in the list.

    ```txt
    ibmcloud cr trash-list
    ```
    {: pre}

6. Verify that the policy is set by running the [`ibmcloud cr retention-policy-list`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_policy_list) command, and check that the policy that you set for the namespace retains the required number of images. If you set the policy to retain all untagged images, ensure that the **`Retain all untagged`** column has the value `true`. If you set a deletion threshold, verify that the **`Deletion threshold (days)`** column shows the correct value.

    ```txt
    ibmcloud cr retention-policy-list
    ```
    {: pre}

## Update a retention policy
{: #retention_policy_update}
{: help}
{: support}

A retention policy is a set of options applied per namespace. There is one policy per namespace, so to update a policy, run the [`ibmcloud cr retention-policy-set`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_policy_set) command again with your new settings. The updated options replace the existing policy immediately, and the policy continues to run daily with the new settings.

For example, to change the number of images to retain to `30` and add a deletion threshold of `14` days for the namespace `NAMESPACE`, run the following command:

```txt
ibmcloud cr retention-policy-set --images 30 --deletion-threshold-days 14 NAMESPACE
```
{: pre}

You can verify the updated policy by running the following command:

```txt
ibmcloud cr retention-policy-list
```
{: pre}

## Update a retention policy to keep all your images
{: #retention_policy_keep}
{: help}
{: support}

All namespaces have a default policy that keeps all images. You can return a policy to the default state.

You can use the [`ibmcloud cr retention-policy-set`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_retention_policy_set) command to set the policy back to the default state by running the following command, where `NAMESPACE` is your namespace:

```txt
ibmcloud cr retention-policy-set --images All NAMESPACE
```
{: pre}

## Clean up your namespaces by deleting untagged images
{: #retention_images_untagged}
{: help}
{: support}

You can clean up your namespace and reduce your bills by deleting your [untagged](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_overview&format=markdown#overview_elements_untagged) images in the namespace and optionally output the results in JSON format.

You can view all your tagged and untagged images by running the [`ibmcloud cr image-digests`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#bx_cr_image_digests) command. If you want to view just your untagged images, you can run the `ibmcloud cr image-digests` command with Go language formatting, see [Example Go format command for `ibmcloud cr image-digests`](https://cloud.ibm.com/docs/Registry?topic=Registry-registry_cli_list&interface=ui&format=markdown#registry_cli_list_imagedigests_go). You can then check that you do want to remove these untagged images before you run the [`ibmcloud cr image-prune-untagged`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#ic_cr_image_prune_untagged) command.
{: tip}

If you want to delete your untagged images and output the results in JSON format, run the following [`ibmcloud cr image-prune-untagged`](https://cloud.ibm.com/docs/Registry?topic=Registry-containerregcli&format=markdown#ic_cr_image_prune_untagged) command, where `NAMESPACE` is your namespace:

```txt
ibmcloud cr image-prune-untagged [--force | -f [--output json]] --restrict NAMESPACE
```
{: pre}