How to Remove Unused Container Images and Objects Using Container Prune

Use container prune to delete stopped containers, container image prune to remove dangling or unused images, and container network prune or container volume prune to clean up networks and volumes no longer attached to containers.

The container CLI from the apple/container repository provides a family of prune commands designed to reclaim disk space by removing unused resources. These commands follow a consistent pattern across containers, images, networks, and volumes, making system maintenance straightforward and safe for automation scripts.

Understanding the Container Prune Command Family

The prune sub-commands target specific resource types that accumulate during development. Each command operates without interactive prompts, allowing them to run safely in CI/CD pipelines.

• container prune: Removes stopped containers from the system.
• container image prune: Deletes dangling images (and optionally all unused images with the -a flag).
• container network prune: Eliminates networks that have no containers currently attached.
• container volume prune: Cleans up data volumes that are not mounted by any running or stopped container.

How Container Prune Works Under the Hood

According to the apple/container source code, the prune logic follows a consistent implementation pattern across resource types, with each command residing in its own Swift file under the ContainerCommands module.

Container Prune Implementation

In Sources/ContainerCommands/Container/ContainerPrune.swift, the command filters the container list to include only stopped instances using ContainerListFilters(status: .stopped) [source lines 35-40]. For each stopped container, the implementation retrieves disk usage statistics via client.diskUsage, then permanently deletes the container using client.delete. The command accumulates the total reclaimed bytes and outputs each pruned container ID followed by a summary log message [source lines 41-66].

Image, Network, and Volume Prune

The same architectural pattern appears in companion files:

• Sources/ContainerCommands/Image/ImagePrune.swift – Handles dangling and unused image removal.
• Sources/ContainerCommands/Network/NetworkPrune.swift – Manages network cleanup logic.
• Sources/ContainerCommands/Volume/VolumePrune.swift – Handles volume deletion.

All implementations share a minimal CLI surface with no extra flags beyond global options like --debug for verbose output, as documented in docs/command-reference.md [source lines 17-27].

Practical Examples for Cleaning Up Resources

Run these commands to reclaim disk space on your host system:

Remove all stopped containers:

container prune

Remove only dangling images (untagged layers not referenced by any container):

container image prune

Remove all unused images, including tagged ones no longer referenced by containers:

container image prune -a

Remove unused networks:

container network prune

Remove unused volumes:

container volume prune

Enable verbose logging with the global --debug flag to see detailed operation information during execution.

Summary

• The container prune, container image prune, container network prune, and container volume prune commands provide targeted cleanup for specific resource types in the apple/container ecosystem.
• The implementation in Sources/ContainerCommands/Container/ContainerPrune.swift filters for stopped containers using ContainerListFilters(status: .stopped), calculates disk usage via client.diskUsage, and performs deletion through client.delete.
• Use the -a flag with container image prune to remove all unused images, not just dangling (untagged) ones.
• All commands accept the --debug flag for verbose output and are designed with minimal CLI surfaces for safe use in automation scripts.

Frequently Asked Questions

What is the difference between container prune and container image prune?

container prune removes stopped containers, while container image prune removes images that are not referenced by any container. The container command affects runtime instances, whereas the image command targets the underlying filesystem layers stored on disk that consume storage space.

Does container prune remove running containers?

No. According to the implementation in Sources/ContainerCommands/Container/ContainerPrune.swift, the command specifically filters for containers with status: .stopped before deletion, ensuring that running containers remain untouched during the cleanup process.

How do I remove all unused images including tagged ones?

Append the -a flag to the image prune command: container image prune -a. Without this flag, the command only removes dangling images (untagged layers), but with -a it removes all images not currently referenced by existing containers, regardless of whether they have tags.

Where can I find the implementation of the prune commands?

The prune logic is implemented in the ContainerCommands source tree within the apple/container repository. Key files include Sources/ContainerCommands/Container/ContainerPrune.swift for containers, Sources/ContainerCommands/Image/ImagePrune.swift for images, Sources/ContainerCommands/Network/NetworkPrune.swift for networks, and Sources/ContainerCommands/Volume/VolumePrune.swift for volumes. User-facing documentation is available in docs/command-reference.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}