Introduction

Deleting Docker images from Nexus Repository Manager is not the same as deleting a normal file from disk. A Docker image in Nexus is represented by manifests, tags, and shared blob layers, so removing one visible tag does not automatically reclaim every byte behind it. In older Nexus 3 setups such as 3.0.1-01, the safe mental model is: delete the image reference first, then run the cleanup or compaction step that removes content no longer referenced.

Understand What You Are Deleting

A Docker repository stores several related pieces:

• tags, such as 1.0.0 or latest
• manifests, which describe an image
• blob layers, which may be shared by several images

This matters because deleting one tag may only remove the manifest reference. Storage is reclaimed only after Nexus confirms that the associated blobs are no longer used anywhere else.

That is why direct filesystem deletion is a bad idea. Nexus keeps internal metadata about those blobs. Removing files behind its back risks repository corruption.

Delete the Image by Manifest, Not by Guesswork

The Docker Registry API deletes images by manifest digest. A typical flow is:

1. ask Nexus for the manifest headers for a given tag
2. capture the Docker-Content-Digest
3. send a DELETE request for that digest

Example:

1curl -u admin:password \
2  -I \
3  -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
4  https://nexus.example.com/v2/myapp/manifests/1.0.0

The response headers include the digest you need, for example sha256:....

Then delete the manifest by digest:

curl -u admin:password \
  -X DELETE \
  https://nexus.example.com/v2/myapp/manifests/sha256:0123456789abcdef

In practice, you should script this carefully and test against a noncritical repository first, because deleting the wrong manifest removes the image reference clients rely on.

Why Space Is Not Freed Immediately

After the delete call, old Nexus 3 installations often still show disk usage that looks too high. That does not necessarily mean the delete failed. It usually means the unreferenced blobs have not yet been cleaned up.

For Docker repositories, Sonatype documentation describes cleanup tasks that remove unused manifests and images. On older Nexus 3 releases, the exact task names and UI layout may differ from newer versions, but the principle is the same: deletion and storage reclamation are separate phases.

So the full process is:

1. delete the manifest or component reference
2. run the cleanup or compaction task
3. verify that the image is gone and the storage usage drops after cleanup finishes

Use Nexus Tasks for Reclamation

If your instance exposes administrative tasks for Docker cleanup or blob-store compaction, use them instead of trying to manipulate the storage manually.

The operational pattern is usually:

• delete old image tags or manifests
• run the task that deletes unused manifests and images
• if applicable, run repository or blob-store compaction afterward

The precise task names depend on Nexus version, but the repository manager should be the thing that decides which blobs are unreferenced.

A Repeatable Cleanup Workflow

A safe operational routine for an older Nexus OSS deployment looks like this:

1# 1. Find the manifest digest for a tag.
2curl -u admin:password \
3  -I \
4  -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
5  https://nexus.example.com/v2/myapp/manifests/old-tag
6
7# 2. Delete that manifest by digest.
8curl -u admin:password \
9  -X DELETE \
10  https://nexus.example.com/v2/myapp/manifests/sha256:0123456789abcdef

Then finish the process in Nexus administration by running the cleanup task appropriate for the repository.

This split is important. The API delete removes the registry reference. The administrative task reclaims the unused content.

UI Versus API

The Nexus UI may let you browse and delete repository components, but Docker users often prefer the registry API because it aligns with Docker image semantics more directly. That said, either method should still be followed by the cleanup task if you want storage back.

So choose based on your operational style:

• UI for occasional, manual cleanup
• API for repeatable image lifecycle scripts

The storage-reclamation rule stays the same in both cases.

Common Pitfalls

The biggest mistake is expecting tag deletion to free space immediately. In Docker repositories, shared layers mean reclamation is deferred until cleanup confirms the blobs are unused.

Another mistake is deleting files directly from the blob store on disk. Nexus metadata will not stay consistent if you bypass the repository manager.

Teams also often delete latest without realizing other environments still pull it. For Docker registries, tag names are part of the deployment contract, so delete deliberately and communicate the change.

Finally, be careful with very old Nexus versions. Features and task names differ from newer releases, so use the version-specific administrative tools available in your deployment rather than copying instructions from a modern screenshot blindly.

Summary

• Docker images in Nexus are stored as manifests, tags, and shared blobs.
• Delete the image reference by manifest digest, not by deleting random files.
• Expect deletion and disk-space reclamation to be two separate steps.
• Run the appropriate Nexus cleanup or compaction task after deleting old images.
• Never manipulate the blob store directly outside Nexus.