Reclaim Harbor Registry Storage by Running Garbage Collection

Problem and takeaway

Deleting an image tag in Harbor does not immediately free the disk or object storage it consumed. The underlying blobs and manifests remain in the registry until garbage collection (GC) identifies them as unreferenced and removes them. If you have deleted or untagged images, running GC is the supported way to reclaim that space.

Takeaway: schedule GC during a low-traffic window, confirm you have recent backups of the Harbor database and storage backend, and verify afterward that your tagged images still pull. GC is irreversible inside Harbor; removed content can only be recovered from a backup.

Desired outcome

• Reclaim storage consumed by unreferenced blobs and manifests.
• Keep all tagged images and their referenced layers intact.
• Confirm success through the Harbor job log and storage metrics.

Prerequisites

• Harbor administrator credentials.
• A maintenance window or confirmed low-traffic period.
• A recent backup of the Harbor database and the configured registry storage backend.
• Enough free space on the backend storage; GC generates significant disk and database read load.
• Knowledge of your Harbor version, because UI paths and scheduling options differ across releases.

Procedure

1. Record baseline storage usage from the Harbor dashboard or your storage provider console, such as local disk metrics, an S3-compatible bucket, OSS, or Azure Blob Storage.
2. Pause or delay non-critical image pushes, pulls, and deployments during the GC window to avoid failed transfers or incomplete layers.
3. Log in to the Harbor portal as an administrator.
4. Navigate to the system settings and locate the garbage collection option. The exact menu location varies by Harbor version; confirm it in your release documentation before starting.
5. Review any version-specific GC options, then start the job. Execution appears as a background job with logs.
6. Monitor the job in Harbor’s background job list until it reaches a terminal state.

Example verification command

From a client machine with Docker installed and network access to the Harbor registry, run:

docker pull REGISTRY_HOST/PROJECT/IMAGE:TAG

Where to run: any machine that can reach the registry endpoint. Required permissions: read or pull access to the repository; Harbor admin privileges are not required for the pull itself. Placeholders: replace REGISTRY_HOST, PROJECT, IMAGE, and TAG with values from your environment. Expected check: the command completes and reports the image as up to date or freshly pulled. Risk: if GC removed a blob still referenced by a tag—which should not happen—the pull fails with a missing layer or manifest error. Do not treat one failed pull as proof of GC failure until you also check the job log and Harbor registry logs.

Expected checks

Check	Where to look	Expected result
GC job status	Harbor background jobs and job log	Completed without fatal errors
Storage usage	Harbor dashboard or storage provider console	Lower than the recorded baseline
Tagged image access	docker pull on a client machine	Succeeds for a sample of tagged images
Registry errors	Harbor registry and core logs	No new blob-not-found or 500 errors after the run

Recovery options

GC permanently deletes data, and Harbor has no built-in undo or rollback for a completed run. Recovery requires restoring the Harbor database and registry storage from backups taken before GC started. Test your backup restore procedure separately before relying on it in an emergency.

Limitations

• GC removes only content unreferenced by any existing image tag; tagged images and their layers are preserved.
• GC does not change or migrate your storage backend.
• It places heavy read load on storage and the database, so avoid running it during active image traffic.
• Exact UI paths, job scheduling fields, and API behavior differ across Harbor versions.

Version assumptions

This guide targets recent Harbor 2.x releases. Menu labels, scheduling options, and behavior can differ between versions. Confirm the GC entry point and available options in your running Harbor version’s documentation before starting.