# Delete a tag or an image

Delete a tag, and the image with its last tag, or delete an untagged image that still costs storage.

Deleting a tag removes the name. When it was the image's last tag, the image goes with it, together
with its signatures and SBOMs. An image no tag points at is deleted on its own. Replace
repository-id with the repository's id and manifest-id with the image's
`manifest.id` from the image list.

**Warning:**
A deleted image cannot be restored, and anything pulling it by digest stops working.

## Prerequisites

- Permission for `ecr:DeleteImage` on the repository. It is allowed in a repository with immutable
  tags too.
- In the console, also `ecr:DescribeRepositories` on the repository; without it the repository's
  page answers 404.

## Delete a tag

**Console**
1. Open **Image repositories**, then open the repository.
2. On the **Images** tab, open the image row's action menu and choose **Delete tag v1.2.0**.
3. Choose **Delete image**.

**CLI**
```sh
dcloud ecr images delete-tag repository-id v1.2.0
```

**API**
```http
DELETE /ecr/api/repositories/repository-id/tags/v1.2.0
```

## Delete an untagged image

The **Images** tab marks such an image **untagged**; the **Tag** filter with **Untagged** lists only
them.

**Console**
1. On the **Images** tab, open the untagged row's action menu and choose
   **Delete untagged image**.
2. Choose **Delete image**.

**CLI**
```sh
dcloud ecr images delete-untagged repository-id manifest-id
```

**API**
```http
DELETE /ecr/api/repositories/repository-id/manifests/manifest-id
```

## Result

- A tag delete answers `200` with `{ tag }`; an untagged image delete answers `200` with
  `{ digest }`.
- When an image is deleted, an `ECR Image Action` event with `action-type` `DELETE` goes to your
  event bus.
- Layers are shared between images, so they are not deleted at once: layer cleanup deletes the ones
  no image uses any more (see [Storage and cleanup](storage-and-cleanup.md)).

## If it is refused

- `409` `This image is still tagged v1.2.0. Delete the tag instead; the image goes with the last one.`
  for an untagged-image delete of an image that has a tag.
- `404` `Not found` when the repository, the tag or the image does not exist.

## Related

- [Set a lifecycle policy](set-a-lifecycle-policy.md) to delete images automatically.
- `ecr.images.delete-tag` · `ecr.images.delete-untagged`
