19.3.1.3 Df Container Usage

The container usage section within docker system df -v expands the Containers row from the default summary into a per-container breakdown. For each container on the host — running or stopped — it reports the container ID, image, command, number of local volumes, writable layer size, creation time, current status, and name. This view identifies exactly how much disk space each container's writable layer occupies and which containers can be safely removed.

Accessing the Container Usage Section

docker system df -v

The container usage table appears after the images section in the verbose output.

Container Usage Table Structure

Containers space usage:

CONTAINER ID    IMAGE           COMMAND               LOCAL VOLUMES   SIZE      CREATED         STATUS              NAMES
a1b2c3d4e5f6    nginx:latest    "/docker-entrypoint"  0               12kB      2 hours ago     Up 2 hours          web_server
b2c3d4e5f6a1    postgres:15     "docker-entrypoint"   1               2.3MB     1 day ago       Exited (0)          db_backup
c3d4e5f6a1b2    alpine:3.18     "/bin/sh"             0               0B        5 days ago      Exited (0)          test_runner
d4e5f6a1b2c3    node:20         "npm start"           0               45MB      3 days ago      Exited (137)        build_failed

CONTAINER ID

The short 12-character prefix of the container's full SHA256 identifier. This ID uniquely identifies the container on the host and can be used directly in docker rm, docker start, docker logs, and other commands.

IMAGE

The image name and tag from which the container was created. If the image has been removed since the container was created, this field shows the image's SHA256 digest instead of a name.

COMMAND

The main command the container is running or ran. This is the entry point plus command combined, truncated to fit the column width.

LOCAL VOLUMES

The number of volumes (named or anonymous) mounted by this container. This count does not include bind mounts from host directories — only Docker-managed volumes. A non-zero value here means the container has associated volume data that persists independently of the container itself.

SIZE

The size of the container's writable layer — the copy-on-write filesystem layer that records all changes the container made on top of its base image. This includes:

• Files created inside the container that are not in the image.
• Files from the image that the container modified (the original is in the image layer; the modified copy is in the writable layer).

The SIZE column does not include the image itself. For example, a postgres:15 container with a 412MB base image and a 2.3MB writable layer shows 2.3MB in the SIZE column, not 414MB.

A container with 0B size has made no changes to the filesystem from the container's perspective (though it may have written extensively to mounted volumes, which are not reflected here).

Large SIZE values indicate containers that wrote heavily to the container filesystem. Common causes include:

• Log files written inside the container to non-volume paths.
• Application cache stored inside the container.
• Build artifacts generated inside a build container.
• Database data written to the container filesystem instead of a volume.

CREATED

A relative timestamp indicating when the container was created. Combined with the STATUS column, this helps identify containers that have been stopped for a long time and are candidates for cleanup.

STATUS

The current state of the container:

• Up <duration>: The container is currently running.
• Exited (0): The container stopped with exit code 0 (successful completion).
• Exited (1), Exited (137), etc.: The container exited with a non-zero code. Exit code 137 specifically indicates the container was killed (typically via SIGKILL, which occurs when docker stop escalates after its timeout, or when docker rm -f is used).
• Created: The container was created but never started.
• Paused: The container is paused.
• Dead: The container was killed but could not be fully cleaned up.

NAMES

The human-readable name assigned to the container, either specified with --name at creation or auto-generated by Docker (two random words joined by an underscore).

Understanding the SIZE Column in Context

The SIZE reported for a container represents only the writable layer. The total actual disk space a container "uses" in the broader sense includes its image layers, but those are shared with other containers using the same image and accounted for separately in the Images section.

Only the writable layer SIZE is shown in the container usage table. The image portion is shown once in the Images section.

Identifying Containers to Remove

From the container usage table, containers suitable for removal are:

• Containers with STATUS Exited (*) that are no longer needed.
• Containers with STATUS Created that were never started.
• Containers with STATUS Dead that failed to clean up.

To remove all stopped containers:

docker container prune

To remove a specific container identified in the table:

docker rm b2c3d4e5f6a1

Or by name:

docker rm db_backup

To inspect the writable layer contents before removing:

docker diff db_backup

To copy files out of a stopped container before deleting it:

docker cp db_backup:/var/log/postgres/backup.log ./backup.log

Containers with Large Writable Layers

If a container shows an unexpectedly large SIZE — for instance, a container showing 2GB in the writable layer — investigate what was written:

docker diff d4e5f6a1b2c3

This shows all files added (A), changed (C), or deleted (D) in the container's writable layer relative to the base image, helping identify where the large files came from before deciding to remove the container.