Enable delete if you need to remove images, because without it the registry only grows. The setting storage.delete.enabled defaults to false. Turning it on lets clients delete blobs and manifests by digest, so pair it with tight access control and a plan for garbage collection.
What the setting does
In the registry configuration, storage.delete.enabled controls whether deleting blobs and manifests by digest is allowed. The default is false. With it off, a delete call is refused. The OCI distribution spec says a registry that has deletion disabled must answer with 400 or 405.
The pull-through cache guide adds a related point: cleanup of cached content requires delete to be enabled in the registry configuration.
Why it is off by default
A registry that cannot delete is simple to reason about. Nothing disappears by accident or by a stolen credential. Once delete is on, anyone with write rights could remove a production image, and your next rollout or autoscale event would fail to pull it.
That is an availability risk, and it also hides evidence. If an incident responder needs the image that ran last week, deletion removes it.
Delete is two steps, not one
Deleting through the API removes the reference and makes the target unreadable through the API. The data stays on disk until garbage collection runs. So two things follow.
- Turning on delete does not free space by itself.
- Disk usage stays flat after a cleanup job until you run collection.
Also, layers are shared. A layer is only collected when no manifest references it, so deleting one image may free little if its layers are used elsewhere.
A sensible approach
- Decide the owner. One service account, run by the platform team, performs deletes through a scheduled job. Developers do not delete by hand.
- Define a retention rule before you automate. Keep released versions and anything currently deployed. Expire untagged and old build images.
- Record what is removed. Log the repository and digest before each delete so you can answer questions later.
- Take a backup of the registry storage before the first large cleanup.
- Schedule garbage collection in a maintenance window, since the docs describe it as stop the world.
- Test in a copy of the registry first.
| Setting | Effect | Risk if careless |
|---|---|---|
| delete disabled | Registry only grows | Disk fills up |
| delete enabled, no controls | Anyone with write can remove images | Outage or lost evidence |
| delete enabled, one owner, logged | Controlled cleanup | Low, if retention is correct |
What to check after
Run a pull of a few known good images by digest. Check that deployed workloads still resolve their references. Confirm disk usage fell after collection, not before it.
If you want to see what your images contain before you decide what to keep, Safeguard can scan container images and generate SBOMs, with a free scan at gold.safeguard.sh/scan.
Quick check
Does deleting an image free disk space right away?
No. The data stays on disk until garbage collection runs, and shared layers stay as long as another manifest uses them.
What does a registry return when delete is disabled?
The OCI distribution spec says it must respond with 400 or 405.
Sources
- Registry configuration reference
- Garbage collection, Distribution docs
- OCI distribution spec
- Registry as a pull-through cache
Last reviewed: 19 October 2026.
