19.3.1 System Df Command

docker system df reports the disk space consumed by Docker resources on the host, broken down by resource type. It shows totals, active usage, total size, and the amount of space that can be recovered by removing unused resources. The command is modeled after the Unix df (disk free) utility and serves as the primary tool for understanding Docker's storage footprint before deciding what to clean up.

Running the Command

docker system df

Default Output

The default output is a summary table with one row per resource type:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          14        5         4.1GB     2.3GB (56%)
Containers      11        3         312MB     278MB (89%)
Local Volumes   7         3         1.4GB     820MB (58%)
Build Cache     62        0         1.1GB     1.1GB

TYPE Column

Identifies the category of Docker resource:

• Images: All images stored on the host, including base images, intermediate layers, and tagged images.
• Containers: All container filesystem layers (writable layers on top of images), including running and stopped containers.
• Local Volumes: All Docker volumes managed by the local driver, whether in use or not.
• Build Cache: Cached layers from docker build or docker buildx build operations.

TOTAL Column

The total number of resources of that type present on the host, regardless of whether they are in use.

ACTIVE Column

The number of resources currently in use:

• For images: Images that are referenced by at least one container (running or stopped).
• For containers: Containers that are currently running.
• For volumes: Volumes mounted by at least one running container.
• For build cache: Build cache entries that are actively referenced by the current build graph (typically 0 when no build is in progress).

SIZE Column

The total disk space consumed by all resources of that type, including both active and inactive ones. This is the actual space occupied on the filesystem.

RECLAIMABLE Column

The amount of space that could be freed by running the corresponding prune command. The percentage in parentheses shows what fraction of the total size is reclaimable.

• For images: Space from dangling images and images not referenced by any container.
• For containers: Space from stopped container writable layers.
• For volumes: Space from volumes not mounted by any container.
• For build cache: All build cache is reclaimable if no build is actively using it.

Verbose Output

The -v flag shows a detailed per-resource breakdown:

docker system df -v

In verbose mode, the output expands each section into individual entries:

Images section:

Images space usage:

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE      SHARED SIZE   UNIQUE SIZE   CONTAINERS
nginx               latest    abc123def456   2 days ago     187MB     0B            187MB         3
postgres            15        def456abc789   1 week ago     412MB     0B            412MB         1
alpine              3.18      789abc012def   3 weeks ago    7.34MB    0B            7.34MB        0
<none>              <none>    012def345abc   5 days ago     245MB     187MB         58MB          0

• SHARED SIZE: Space shared with other images through common layers (not counted in unique storage).
• UNIQUE SIZE: Space used exclusively by this image and not shared with any other image.
• CONTAINERS: Number of containers using this image.

Containers section:

Containers space usage:

CONTAINER ID    IMAGE     COMMAND    LOCAL VOLUMES   SIZE      CREATED        STATUS         NAMES
a1b2c3d4e5f6    nginx     ...        0               2.3kB     2 hours ago    Up 2 hours     web
b2c3d4e5f6a1    postgres  ...        1               1.5MB     1 day ago      Exited (0)     db_backup

• LOCAL VOLUMES: Number of volumes mounted by this container.
• SIZE: Size of the container's writable layer (changes made on top of the image).

Volumes section:

Local Volumes space usage:

VOLUME NAME         LINKS     SIZE
postgres_data       1         512MB
app_uploads         0         124MB
cache_data          0         76MB

• LINKS: Number of containers currently mounting this volume.

Build Cache section:

Build cache usage: 1.1GB

CACHE ID          CACHE TYPE    SIZE      CREATED        LAST USED      USAGE     SHARED
abc123            regular       245MB     3 days ago     3 days ago     1         false
def456            regular       187MB     5 days ago     5 days ago     0         false

Interpreting the Output for Cleanup Decisions

The reclaimable column is the primary indicator of cleanup opportunity:

• High reclaimable percentage on Images suggests many unused or dangling images. Run docker image prune or docker image prune --all.
• High reclaimable on Containers means many stopped containers exist. Run docker container prune.
• Any reclaimable on Local Volumes means orphaned volumes. Run docker volume prune (carefully — verify named volumes are truly unused).
• All Build Cache is typically reclaimable. Run docker builder prune or docker system prune to clear it.

Using --format

The --format flag accepts a Go template to customize output:

docker system df --format "{{.Type}}: {{.Size}} (reclaimable: {{.Reclaimable}})"

Available fields: .Type, .Total, .Active, .Size, .Reclaimable.

Practical Workflow

Before a cleanup, always run df first to understand the scope:

docker system df

Identify where the most reclaimable space is, then target that resource type:

docker image prune --all
docker container prune --force
docker volume prune --force
docker builder prune --force

Verify the result:

docker system df

Running docker system df before and after cleanup confirms how much space was actually recovered and whether any resources remain that could not be pruned because they are still in use.