19.3.2.2 Prune Stopped Containers

When docker system prune runs, one of the resource types it targets is stopped containers. All containers that are not currently running — regardless of when they stopped or why — are considered candidates for removal. This encompasses containers in the Exited, Created, and Dead states. The operation is equivalent to running docker container prune as a component of the broader system cleanup.

What Counts as a Stopped Container for Pruning

Docker's prune logic considers three container states as "stopped":

• Exited: The container ran and its main process terminated. The exit code may be 0 (success) or non-zero (error or kill signal). All exited containers are pruned regardless of exit code.
• Created: The container was created with docker create or docker run but was never started. These containers exist only as metadata with an allocated filesystem layer and no execution history.
• Dead: The container was killed but the Docker daemon failed to fully remove it during the kill operation. These are in an inconsistent state and are cleaned up by pruning.

Running containers and paused containers are excluded from pruning entirely.

How Stopped Containers Accumulate

On a busy Docker host, stopped containers accumulate continuously:

• Every docker run invocation without --rm leaves a stopped container after the process exits.
• Every docker stop on a long-running service produces a stopped container.
• Every failed container (crashed applications, build failures) leaves an exited container behind.
• In CI/CD environments, each pipeline job may run multiple containers that exit after their step completes.

Without active cleanup, a host that runs hundreds of build jobs per day can accumulate thousands of stopped containers within weeks.

Effect on Disk Space

Each stopped container holds its writable filesystem layer — the copy-on-write layer that recorded all changes the container made on top of its image. This layer persists until the container is removed. For most application containers that primarily write to mounted volumes, this layer is small (a few kilobytes to a few megabytes). For containers that wrote heavily to the container filesystem — build containers that downloaded dependencies, containers that wrote logs internally — this layer can be several gigabytes.

Running docker container prune removes these writable layers and reclaims the associated disk space.

Confirming What Will Be Removed

Before pruning, verify which stopped containers exist:

docker ps -a --filter status=exited
docker ps -a --filter status=created

To see the size each stopped container's writable layer is consuming:

docker system df -v

Look at the Containers section in the verbose output. The SIZE column shows the writable layer size for each container, and the STATUS column identifies which containers are stopped.

Running the Prune

To prune stopped containers as part of a full system cleanup:

docker system prune

To prune only stopped containers without affecting images, volumes, or other resource types:

docker container prune

Both commands display a confirmation prompt before removing anything:

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N]

After confirmation:

Deleted Containers:
a1b2c3d4e5f6
b2c3d4e5f6a1
c3d4e5f6a1b2

Total reclaimed space: 156MB

To skip the confirmation for automated use:

docker container prune --force

Or as part of system prune:

docker system prune --force

Filtering by Age

To prune only containers that stopped more than a certain time ago (preserving recently stopped containers for inspection):

docker container prune --filter "until=24h"

This removes containers that exited or were created more than 24 hours ago. Containers stopped within the last 24 hours are left available for debugging.

Duration formats: 24h (hours), 90m (minutes), 3600s (seconds). Absolute timestamps in RFC3339 format also work.

Filtering by Label

To prune only containers carrying a specific label (useful in multi-project environments):

docker container prune --filter "label=project=staging"

This removes only stopped containers that have the label project=staging, leaving other stopped containers intact.

What Is Not Removed

• Running and paused containers.
• Named volumes associated with stopped containers. These persist and must be removed separately with docker volume prune.
• Anonymous volumes associated with stopped containers. These also persist unless you used docker rm -v before the container stopped, or until docker volume prune is run.
• The image each stopped container was built from. Images are separate resources managed independently.

Impact of Removing Stopped Containers

Removed containers cannot be restarted. Their writable filesystem layers are gone, including any data written inside the container to non-volume paths. If a stopped container holds logs, generated files, or application output that was not extracted before removal, that data is permanently lost.

Before pruning, extract any needed data:

docker cp my_stopped_container:/app/output.json ./output.json
docker logs my_stopped_container > container_output.log

After running the prune, verify the container list is clean:

docker ps -a

Only running and intentionally retained containers should remain.