> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/containers/private-container-registry/dcd-how-tos/container-registry-garbage-collection-settings.md).
# Private Container Registry Garbage Collection Settings
Each Private Container Registry offers a configurable Garbage Collection schedule to reclaim storage space from deleted images. Garbage Collection is turned off by default, giving you full control over when and how cleanup occurs. For more information, see the [Garbage collection FAQ](/cloud/containers/private-container-registry/faqs.md#garbage-collection).
Understand the following key behaviors before configuring garbage collection:
{% hint style="info" %}
**Note:**
* **Read-only mode:** During garbage collection, the Private Container Registry enters a read-only state. Workloads can still pull images, but you cannot push images while the process runs. Schedule garbage collection during low-traffic windows.
* **Timing of storage recovery:** Deleting an image or tag does not immediately free storage space. The Private Container Registry hides deleted items from view, but the underlying data remains on disk. The Private Container Registry reclaims storage only after garbage collection completes. The size of the Private Container Registry determines how long garbage collection takes.
* **Billing impact:** Your invoice reflects actual disk usage. Storage recovery and billing updates occur after garbage collection finishes.
{% endhint %}
## How garbage collection works
Garbage collection reclaims storage by removing orphaned data that no images reference. Before you begin, familiarize yourself with the following key terms:
* **Layer:** A unit of container image data. Example: an operating system base image, application code. One layer can be shared by multiple images.
* **Image manifest:** A metadata record that lists all layers in an image. Deleting the manifest tells the Private Container Registry the image is no longer needed.
* **Tag:** A human-readable label that points to a manifest. Example: `v1.0.0`. One manifest can have multiple tags.
* **Untagged image:** An image without a tag, identified only by its digest (a unique hash). Example: `SHA256`. Modern container workloads often reference images by digest instead of tag.
### The cleanup flow
1. You delete one or more image manifests, either by tag or digest.
2. Garbage collection scans for manifests marked as deleted and checks which layers are still referenced by active images.
3. Layers with no active references are permanently deleted from the disk.
4. Storage usage decreases and billing is updated.
{% hint style="info" %}
**Garbage collection duration:** Completion time depends on the Private Container Registry size and the number of layers to scan.
{% endhint %}
## How should I clean up my images?
Use the decision matrix to arrive at a solution:
| **Scenario** | **Action** | **Time to storage recovery** |
| -------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- |
| Delete an image by tag. Example: `app:old-version` | Delete using the DCD or API; run garbage collection | Storage is reclaimed after garbage collection completes |
| Delete an untagged image (digest-based) | Delete using the API or `regctl`, then wait for garbage collection to run | Storage is reclaimed after garbage collection completes |
| Immediate visibility removal needed | Delete immediately using the DCD; garbage collection runs later | Immediate visibility; delayed garbage collection |
## Configure garbage collection
To turn on the garbage collection and set a recurring schedule from the DCD:
{% hint style="info" %}
**API-based configuration:** You can also configure garbage collection through the API for more granular control. Example: custom intervals, manual triggers. For more information, see [API documentation](https://api.ionos.com/docs/containerregistry/v1/).
{% endhint %}
1\. In the **DCD**, go to **Menu** > **Containers** > **Container Registry**.
2\. Select a Private Container Registry to configure garbage collection. You can also select the **OPTIONS** menu  > **Properties**.
3\. In the **Properties** tab, click **>** in the **Garbage Collection** row to expand the configuration panel.
4\. Select a **Day** and **Time (UTC)** for garbage collection to run on a weekly basis. Choose a time when workload traffic is minimal. Read-only mode prevents pushes and pulls during cleanup.
5\. Click **Update Schedule** to save your settings.
{% hint style="success" %}
**Result:** Garbage collection now runs automatically at your chosen time each week.
{% endhint %}
## Delete images
To free storage space, follow the sequence:
{% stepper %}
{% step %}
### Delete the image manifest
Mark images for deletion using one of these methods mentioned in the following tabs:
{% tabs %}
{% tab title="From the DCD (by tag)" %}
1. Navigate to your Private Container Registry.
2. Find the image and tag you want to delete.
3. Click the **OPTIONS** menu and select **Delete**.
4. Confirm the deletion.
The image is now hidden from the DCD, but the underlying data remains on disk.
{% endtab %}
{% tab title="Using API or `regctl` (by digest)" %}
To delete untagged images by digest or automate the process, use the API or the `regctl` command-line tool.
Option A: Using `regctl` (recommended for simplicity)
```bash
regctl image delete //@
```
Replace the placeholders:
* ``: Your Private Container Registry URL. Example: `registry.example.com`
* ``: The repository path. Example: `my-app`
* ``: The image name. Example: `api-server`
* ``: The image digest. Example: `sha256:abc123...`
Example:
```bash
regctl image delete registry.example.com/my-app/api-server@sha256:abc123def456
```
Option B: Using the Registry API directly
{% hint style="info" %}
**Docker CLI limitation:** The standard Docker CLI (`docker image rm`) does not support deleting images from a remote Private Container Registry. Use `regctl` or the API instead.
{% endhint %}
1\. Obtain an authentication token:
```bash
curl -u : \
"https:///auth/token?scope=repository:/:pull,delete&service="
```
Replace placeholders and copy the token from the response.
2\. Delete the manifest using the token:
```bash
curl -X DELETE \
-H "Authorization: Bearer " \
-H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
"https:///v2///manifests/"
```
{% hint style="success" %}
**Result:** The server returns an **HTTP 202** status when it accepts a manifest deletion request for background processing.
{% endhint %}
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### Run garbage collection
After deleting manifests, trigger garbage collection to reclaim storage:
1\. Wait for your scheduled garbage collection time, or contact support to request an immediate run.
2\. During execution, your Private Container Registry will be in read-only mode.
3\. After completion, check your storage metrics in the DCD to confirm the reduction.
{% hint style="success" %}
**Result:** Orphaned layers are deleted from disk and storage usage decreases.
{% endhint %}
{% endstep %}
{% endstepper %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ionos.com/cloud/containers/private-container-registry/dcd-how-tos/container-registry-garbage-collection-settings.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.