19.3.2.1 Prune Unused Data

Pruning unused data in Docker refers to the process of removing resources that are no longer referenced by any active or relevant container. When docker system prune runs, it evaluates each resource type against a definition of "unused" and removes those that qualify. Understanding what makes a resource unused is important because the criteria differ between resource types.

Unused Containers

A container is considered unused when it is not currently running. Any container with status Exited, Created, or Dead qualifies for pruning. These containers retain their writable filesystem layers on the host, consuming disk space, until they are explicitly removed.

Containers with status Up (running) or Paused are not pruned.

docker container prune

This removes all stopped containers and is the equivalent of the container portion of docker system prune.

Unused Networks

A network is considered unused when no running container is currently connected to it. Stopped containers that were connected to the network do not count — only actively running container connections matter.

Docker's three default networks (bridge, host, none) are never pruned regardless of whether containers are connected to them.

docker network prune

Unused Images

Docker distinguishes between two levels of "unused" for images:

Dangling images (the default threshold for pruning) are images with no name tag and no reference from any container. They appear as <none>:<none> in docker images output and result from building a new image with the same tag as an existing one, which detaches the tag from the old image and leaves it untagged.

Unused images (the broader threshold, enabled with --all) are images that are not referenced by any container — running or stopped. This includes tagged images that are stored locally but not currently in use by any container.

docker image prune

Removes only dangling images.

docker image prune --all

Removes all images not used by any container.

Unused Volumes

A volume is considered unused when it is not mounted by any container — running or stopped. Named volumes with 0 mounts and anonymous volumes whose container no longer exists both qualify.

By default, docker system prune does not remove volumes. You must explicitly add --volumes:

docker system prune --volumes

Or prune volumes directly:

docker volume prune

The distinction between running and stopped containers matters here: a volume mounted by a stopped (but not yet removed) container is still considered referenced and will not be pruned.

Unused Build Cache

Build cache entries are considered unused when they are not currently required by an in-progress build. Since build cache is not referenced by containers, images, or volumes in a persistent way — it only accelerates future builds — all build cache entries are effectively reclaimable as long as no build is actively running.

docker builder prune

Removes all build cache. Adding --filter until=<duration> removes only entries that have not been used recently:

docker builder prune --filter "until=48h"

The "Until" Filter

The --filter until=<duration> option allows all prune commands to limit removal to resources that have been unused for longer than the specified duration:

docker system prune --filter "until=72h"

This is useful for preserving recently stopped containers for debugging, keeping recently built images for fast iteration, and maintaining recent build cache for quicker local builds.

Duration formats supported: 72h (hours), 30m (minutes), 120s (seconds). Absolute timestamps in RFC3339 format are also accepted:

docker system prune --filter "until=2024-03-01T00:00:00"

The Label Filter

The --filter label=<key>=<value> option restricts pruning to resources that carry a specific label:

docker system prune --filter "label=environment=test"

This removes only resources labeled with environment=test, leaving production or staging resources untouched.

What "Unused" Does Not Mean

It is important to note that "unused" in Docker's pruning context does not mean "unimportant" or "safe to delete." A stopped database container may be unused in the pruning sense but contain critical application data in its writable layer. A named volume with 0 links may hold database files from a stopped service that will be needed again.

Before running prune commands, always use docker system df -v to review what will be removed:

docker system df -v

And confirm no containers with valuable unextracted data or volumes with important stored data would be pruned. For data that needs to survive container removal, always use named volumes or bind mounts to store it outside the container's writable layer.