> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/artifacts/delete-an-artifact.md).

# Delete an artifact

Soft delete or permanently delete an artifact or version, find deleted items on the Deleted view, and restore them before the retention window closes.

{% hint style="info" %}
This feature is in Beta[^1] and requires enablement. [View all early access features.](https://developer.harness.io/release-notes/features.md)

{% @harness-feature-flag-access/request-feature-flag-access module="artifacts" pagePath="artifacts/artifacts/delete-an-artifact" pageTitle="Delete%20an%20artifact%20or%20version" featureFlags="%5B%7B%22name%22%3A%22Soft%20delete%20for%20artifacts%22%2C%22key%22%3A%22HAR\_SOFT\_DELETE\_SUPPORT%22%2C%22status%22%3A%22BETA%22%2C%22description%22%3A%22Enables%20soft%20delete%20for%20packages%20and%20versions%2C%20with%20a%20configurable%20retention%20window%20before%20permanent%20removal.%22%7D%5D" %}
{% endhint %}

Harness Artifacts supports two deletion modes:

* **Soft delete**: Moves the artifact or version to a recoverable **Deleted** state. The item is no longer downloadable but stays in storage until the retention window expires. You can restore it any time before then.
* **Permanent delete**: Removes the item immediately and cannot be undone.

When soft delete is enabled for your account, Harness defaults to soft delete. You can switch to permanent delete in the confirmation dialog.

{% hint style="info" %}
**Upstream proxy registries**

Artifacts deleted from an upstream proxy registry are removed from the local cache only. To retrieve them again, Harness must re-pull them from the remote source. Go to [Create an upstream proxy](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md) for details.
{% endhint %}

## Before you begin

Your role must include the **Delete Artifact** permission on the registry. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) to review permission requirements.

A version that is actively deployed through Harness CD or protected by a retention rule may be blocked from deletion. When this happens, the error message identifies the blocking condition.

## Delete an artifact or version

1. Navigate to the artifact you want to delete. You can reach it from the global **Artifacts** list or from a registry's **Packages** tab.
2. To delete a specific version, open the artifact and go to its version list.
3. Click the three-dot menu (**⋮**) next to the artifact or version.
4. Select **Delete**.
5. In the confirmation dialog, type the exact name to confirm.
6. To permanently delete instead of soft delete, select the **Permanently delete** checkbox.
7. Click **Delete**.

When you soft delete an artifact (the package), all its versions are soft deleted at the same time.

### What happens to clients after a soft delete

Soft deleted items are immediately non-downloadable:

* A pull of a soft deleted Docker image returns HTTP 404 with `MANIFEST_UNKNOWN`.
* A pull of a soft deleted Maven, Python, or Generic artifact returns HTTP 404.
* If the registry has an upstream proxy configured, a pull may still succeed from the upstream source.

Soft deleted items continue to count toward your storage usage until Harness purges them.

## Find deleted items

Soft deleted items move to a **Deleted** view.

### From the global Artifacts list

1. In the navigation menu, select **Artifacts**.
2. Click **Show**.
3. Select **Deleted**.

Use the **Registries** and **Package Types** filters to narrow the results.

### From inside an artifact

1. Open the artifact.
2. In the version list, look for the **Deleted** section, which appears after the available versions.

If the artifact itself was soft deleted, the artifact header shows a DELETED state while the deleted versions remain visible inside.

## Restore a deleted item

From the **Deleted** view or the deleted section within an artifact, click the three-dot menu (**⋮**) and select **Restore**.

Restoring a version also restores the parent artifact if it was soft deleted. You do not need to restore the artifact separately before restoring a version.

## Permanently delete a soft deleted item

To remove a soft deleted item before the retention window expires:

1. Go to the **Deleted** view.
2. Click the three-dot menu (**⋮**) next to the item.
3. Select **Delete**.

This is permanent and cannot be undone. Storage usage decreases at the next measurement cycle.

## Configure the retention period

Account administrators set how long soft deleted items are kept before Harness purges them.

1. Go to **Account Settings** > **Default Settings**.
2. Under **Artifact Registry**, set the **Soft Delete Retention Period**.

The field accepts a whole number from 1 to 3650 (days). The default is 30 days. One retention period applies to the entire account; it cannot be overridden per organization or project.

Changing the period applies to all existing soft deleted items immediately. If you shorten it, items already in the Deleted view may be purged at the next scheduled purge run if they are older than the new value.

## Delete using the API

The delete API endpoints require the artifact **digest** (SHA hash), not the tag name. To retrieve the digest, open the version details page and copy it from the version selector or pull command.

* Soft delete: call the delete endpoint with `force=false` or omit the parameter.
* Permanent delete: call the delete endpoint with `force=true`.

Relevant endpoints: `deleteregistryv3`, `deletepackagev3`, `deleteversionv3`. Go to the [Harness API documentation](https://apidocs.harness.io) for full reference.

## Troubleshooting

<details>

<summary>I deleted a tag but the image still appears in the registry</summary>

Deleting a tag removes only that label. The image stays in the registry, accessible by its digest, until you delete the version itself. To remove the image, open the artifact's version list and delete the specific version by its digest.

</details>

<details>

<summary>Can I delete an artifact that is quarantined?</summary>

Yes. Quarantine blocks pull and download operations but does not block deletion. If a retention rule or an active Harness CD deployment is protecting the version, the delete fails and the error message identifies the blocking condition. To restore pull access without deleting, select **Remove from Quarantine** instead.

</details>

<details>

<summary>The Delete option does not appear in the menu</summary>

Your role may not include the **Delete Artifact** permission. Contact your account administrator to review your role assignments. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) for the permission list.

</details>

<details>

<summary>Are soft deleted items counted against my storage quota?</summary>

Yes. Soft deleted items remain in storage and continue to count toward your storage usage until Harness purges them at the end of the retention window. To free storage immediately, select the item in the Deleted view and permanently delete it.

</details>

<details>

<summary>How do I soft delete or permanently delete using the API?</summary>

Use the v3 delete API endpoints with the `force` query parameter. Set `force=false` (or omit it) for soft delete, or `force=true` for permanent delete. Endpoints: `deleteregistryv3`, `deletepackagev3`, and `deleteversionv3`. Go to the [Harness API documentation](https://apidocs.harness.io) for full reference and authentication details.

</details>

## Next steps

* [Browse and search artifacts](https://developer.harness.io/artifact-registry/3.0/artifacts/browse-and-search.md)
* [Copy a version to another registry](https://developer.harness.io/artifact-registry/3.0/artifacts/copy-a-version.md)
* [Lifecycle management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md)

[^1]: Off by default. If you want to try it and share feedback, request access and Harness will turn it on for your account. Beta features can change and may not be ready for production use.
