Glossary

Garbage Collection

An automated process that reclaims storage space within a container registry by deleting unreferenced or untagged image manifests and orphaned layer blobs.

Get in touch Learn more

Developer building agentic RAG system, retrieval pipeline diagram on laptop, technical workspace with notes.

REGISTRY MAINTENANCE

What is Garbage Collection?

Garbage collection is an automated process that reclaims storage space within a container registry by deleting unreferenced or untagged image manifests and orphaned layer blobs.

Garbage collection is the automated process of identifying and deleting orphaned layer blobs and unreferenced manifests in a container registry. Because registries use content-addressable storage, layers are shared across multiple image tags. When a tag is deleted or overwritten, the underlying layers are not immediately removed, as they may still be referenced by other manifests. The garbage collector performs a mark-and-sweep operation, traversing all reachable manifests and deleting any blobs not associated with a current reference.

In air-gapped and private container registries, garbage collection is critical for managing storage quotas and reducing costs. Without it, continuous integration pipelines that push frequent builds with unique tags rapidly consume terabytes of disk space. The process is typically invoked manually or on a schedule via the registry's administration API, and it must be executed during a read-only maintenance window to prevent race conditions with concurrent pushes. A properly configured retention policy often complements garbage collection by automatically untagging stale images before the sweep.

GARBAGE COLLECTION

Key Characteristics

The automated process that reclaims storage space within a container registry by deleting unreferenced or untagged image manifests and orphaned layer blobs.

Manifest Deletion Logic

Garbage collection identifies manifests that are no longer referenced by any tag. When a tag is overwritten or deleted, the underlying manifest becomes untagged. The GC process scans for these untagged manifests and removes them, breaking the link between the manifest and its associated layers. This is the first phase of a two-phase deletion process.

Blob Orphan Detection

After manifests are deleted, the GC process identifies orphaned blobs—filesystem layers that are no longer referenced by any remaining manifest. Because container registries use content-addressable storage, a single blob may be shared across multiple images. GC must perform a mark-and-sweep algorithm to determine which blobs are truly unreachable before deletion.

Mark-and-Sweep Algorithm

The standard GC implementation uses a two-phase mark-and-sweep approach:

Mark Phase: Traverses all reachable manifests and marks every referenced blob as live.
Sweep Phase: Iterates over all stored blobs and deletes any that were not marked. This ensures that shared layers are preserved even when one referencing image is removed.

Registry Consistency Locking

During garbage collection, the registry typically enters a read-only mode to prevent race conditions. If a push operation were to upload a new manifest referencing a blob that GC is about to delete, data corruption would occur. Production registries like Harbor and Docker Distribution implement file-level locking or maintenance windows to ensure atomicity.

Retention Policy Integration

Garbage collection is often triggered by retention policies that define which images to keep. Policies may specify:

Keep the last N versions per repository
Retain images deployed in the last 90 days
Preserve images with specific immutable tags GC executes the policy decisions by removing everything outside the retention window.

Untagged vs. Unreferenced

A critical distinction in GC behavior:

Untagged: A manifest with zero associated tags. These are always candidates for deletion.
Unreferenced: A manifest that is tagged but not referenced by any running workload. GC does not typically delete these unless a retention policy explicitly targets them. Understanding this distinction prevents accidental deletion of production images.

GARBAGE COLLECTION

Frequently Asked Questions

Essential questions about how container registries reclaim storage space by removing unreferenced manifests and orphaned layer blobs.

Garbage collection is an automated maintenance process that reclaims disk space within a container registry by permanently deleting unreferenced image manifests and orphaned layer blobs that are no longer associated with any tagged or referenced artifact. Unlike a simple file deletion, garbage collection operates on the registry's content-addressable storage model, where blobs are shared across multiple images. The process must first identify which blobs are still reachable through any tag or manifest reference, then safely remove only those blobs that have become completely disconnected from the registry's object graph. This is critical in private registries where CI/CD pipelines generate hundreds of ephemeral builds daily, rapidly consuming terabytes of storage with intermediate layers that are never deployed to production.

Enabling Efficiency, Speed & Accuracy

Intelligent Analysis, Decision & Execution

We build AI systems for teams that need search across company data, workflow automation across tools, or AI features inside products and internal software.

Talk to Us

Search across company data

Give teams answers from docs, tickets, runbooks, and product data with sources and permissions.

Useful when people spend too long searching or get different answers from different systems.

Enterprise searchRAGPermissions

Automate internal workflows

Use AI to route work, draft outputs, trigger actions, and keep approvals and logs in place.

Useful when repetitive work moves across multiple tools and teams.

AI agentsWorkflow automationGovernance

Add AI to products and internal tools

Build assistants, guided actions, or decision support into the software your team or customers already use.

Useful when AI needs to be part of the product, not a separate tool.

AI integrationDecision supportModel routing

REGISTRY LIFECYCLE

Related Terms

Garbage collection is tightly coupled with the policies and mechanisms that govern image lifecycle, storage integrity, and security enforcement within a private registry.

Retention Policy

A user-defined rule set that automatically removes container images from a registry based on criteria like tag count, age, or vulnerability severity. Retention policies define the what and when of deletion, while garbage collection executes the how by reclaiming the orphaned storage blobs.

Tag-based rules: Keep only the last 5 images per repository
Time-based rules: Remove images older than 30 days
Vulnerability-based rules: Auto-delete images with critical CVEs

30-60%

Typical storage reduction

Content-Addressable Storage

A storage architecture where data blobs are located and retrieved by a cryptographic hash of their content rather than by a mutable name. This is the foundational mechanism that makes garbage collection possible—the registry can safely delete a blob only when no manifest references its specific hash.

Ensures deduplication: identical layers are stored once
Guarantees integrity: content cannot be altered without changing the address
Enables safe deletion: unreferenced hashes are provably orphaned

Image Digest

A unique, content-addressable SHA256 hash that immutably identifies a specific container image manifest or layer. Garbage collection algorithms traverse the directed acyclic graph of digests to determine which blobs are still reachable from a tagged manifest.

Format: sha256:64a4f8e...
Immutable: any change to the image produces a new digest
Used as the root node in mark-and-sweep GC traversal

Image Tagging Strategy

A systematic convention for assigning mutable or immutable tags to container images. Tagging strategy directly impacts garbage collection efficacy—mutable tags like latest can orphan previously referenced manifests, creating more garbage.

Immutable tags (Git SHA, digest): prevent accidental orphaning
Mutable tags (latest, staging): increase GC workload
Semantic versioning: balances traceability with cleanup predictability

Image Promotion

The process of copying a container image between distinct registry namespaces or repositories to advance it through a CI/CD pipeline. Promotion creates new references to existing blobs, which must be tracked by the garbage collector to prevent premature deletion of shared layers.

Dev → Staging → Production promotion chains
Cross-repository blob sharing reduces storage but complicates GC
Requires reference counting across namespaces

Cosign

A tool under the Sigstore project used to cryptographically sign container images and OCI artifacts. Signatures are stored as separate OCI artifacts alongside the image in the registry. Garbage collection must account for these attached artifacts—deleting an image should also clean up its orphaned signatures.

Signatures stored as .sig OCI artifacts
Referenced via the subject manifest digest
GC must traverse signature-to-manifest relationships

About the author

Prasad Kumkar

CEO & MD, Inference Systems

Prasad Kumkar is the CEO & MD of Inference Systems and writes about AI systems architecture, LLM infrastructure, model serving, evaluation, and production deployment. Over 5+ years, he has worked across computer vision models, L5 autonomous vehicle systems, and LLM research, with a focus on taking complex AI ideas into real-world engineering systems.

His work and writing cover AI systems, large language models, AI agents, multimodal systems, autonomous systems, inference optimization, RAG, evaluation, and production AI engineering.

Limited slotsGet a Free AI Consultation

How We Work

Custom AI workflows for your Business

One-fit-all AI don't work for modern businesses. At Inferensys, we aim to understand your business & custom requirements; which we use to define most efficient agentic workflows, the data, and the tools for your business.