How to View Disk Usage for Containers and Volumes with `container system df`

Use container system df to inspect disk consumption across images, containers, and volumes, with support for human-readable tables or machine-parsable JSON/YAML output.

The container CLI from the apple/container repository provides a native way to monitor storage utilization in your container runtime. The container system df command aggregates filesystem statistics from the local daemon and presents them in configurable formats, making it essential for capacity planning and cleanup automation. This guide explains the command's architecture, implementation details, and practical usage patterns.

Understanding the container system df Command

container system df reports disk usage across three distinct resource categories managed by the container runtime:

• Images – All image layers stored locally, including intermediate build caches.
• Containers – Writable container layers and associated metadata.
• Local Volumes – Persistent data volumes managed by the runtime.

The output displays four key metrics for each category: TOTAL (object count), ACTIVE (currently running or referenced), SIZE (total bytes consumed), and RECLAIMABLE (bytes safe to delete via pruning).

How the Command Works Under the Hood

CLI Entry Point

The command implementation resides in Sources/ContainerCommands/System/SystemDF.swift. The run() method acts as the primary entry point, invoking ClientDiskUsage.get() to initiate an asynchronous fetch operation. This abstraction keeps the CLI layer decoupled from transport specifics.

API Client and Data Retrieval

The ClientDiskUsage struct, located in Sources/Services/ContainerAPIService/Client/DiskUsage.swift, handles the actual communication. It transmits a gRPC/REST request to the local container-apiserver daemon, which gathers filesystem statistics from the underlying storage driver. The server returns a serialized DiskUsageStats payload containing raw byte counts for all resource types.

Data Model Structure

The DiskUsageStats struct encapsulates three ResourceUsage instances—one each for images, containers, and volumes. Each ResourceUsage object tracks:

• total – Total number of objects in this category.
• active – Count of objects currently in use or running.
• sizeInBytes – Raw disk consumption.
• reclaimable – Bytes eligible for deletion without affecting running workloads.

Output Rendering and Formatting

After receiving the payload, the CLI passes data to Output.render. When invoked without flags, the default table format is generated by diskUsageTable() within SystemDF.swift. The helper formatSize() leverages ByteCountFormatter to produce human-readable strings (e.g., "1.2 GB"), while formatReclaimable() calculates percentages and caps values at 100% for safety.

The --format flag accepts json, yaml, toml, or table, serializing the same DiskUsageStats object into the requested representation. This design ensures consistent data structures across all output formats.

Practical Examples for Viewing Disk Usage

Basic Table View

Execute the command without arguments to see the default human-readable table:

container system df

Typical output:

TYPE           TOTAL  ACTIVE  SIZE      RECLAIMABLE
Images         12     3       1.8 GB    200 MB (11%)
Containers     5      2       350 MB    150 MB (43%)
Local Volumes  8      4       2.4 GB    0 B (0%)

JSON Output for Automation

For scripting and CI pipelines, use structured JSON output:

container system df --format json

Example output:

[
  {
    "images": {
      "total": 12,
      "active": 3,
      "sizeInBytes": 1932735283,
      "reclaimable": 209715200
    },
    "containers": {
      "total": 5,
      "active": 2,
      "sizeInBytes": 367001600,
      "reclaimable": 157286400
    },
    "volumes": {
      "total": 8,
      "active": 4,
      "sizeInBytes": 2576980377,
      "reclaimable": 0
    }
  }
]

Parse specific values using jq:

container system df --format json | jq '.[0].volumes.reclaimable'

YAML and Other Formats

Generate YAML for configuration management or documentation:

container system df --format yaml

The command also supports toml for environments where TOML configuration is standard.

Automating Prune Decisions

Combine JSON output with shell scripting to conditionally reclaim space:

#!/bin/bash
stats=$(container system df --format json)
reclaimable=$(echo "$stats" | jq '[.[0].images.reclaimable, .[0].containers.reclaimable, .[0].volumes.reclaimable] | add')
total=$(echo "$stats" | jq '[.[0].images.sizeInBytes, .[0].containers.sizeInBytes, .[0].volumes.sizeInBytes] | add')

percent=$(awk "BEGIN {print ($reclaimable/$total)*100}")

if (( $(echo "$percent > 30" | bc -l) )); then
    container system prune --filter "until=24h"
fi

Summary

• container system df queries the local container-apiserver to report disk usage across images, containers, and volumes.
• The command maps to Sources/ContainerCommands/System/SystemDF.swift, which orchestrates ClientDiskUsage.get() and formats output via diskUsageTable().
• Data model fields include total, active, sizeInBytes, and reclaimable as defined in Sources/Services/ContainerAPIService/Client/DiskUsage.swift.
• Output formats include human-readable tables (default) and machine-parsable JSON, YAML, or TOML via the --format flag.
• Automation is straightforward using JSON output piped to tools like jq, enabling CI pipelines to enforce storage policies before invoking container system prune.

Frequently Asked Questions

What does the reclaimable column mean in container system df?

The reclaimable column indicates bytes that can be freed without affecting running containers or active volumes. According to the DiskUsageStats implementation, this value represents unused image layers, stopped container writable layers, and unreferenced volumes. The percentage displayed is calculated by formatReclaimable() and capped at 100% to prevent display anomalies.

How does container system df differ from docker system df?

While both commands display similar resource categories, container system df integrates with the apple/container runtime's specific container-apiserver architecture. The implementation in Sources/ContainerCommands/System/SystemDF.swift uses Swift's ByteCountFormatter for localization and supports TOML output in addition to JSON and YAML, differing from Docker's implementation details.

What permissions are required to run container system df?

The command runs without elevated privileges in most configurations. It queries the daemon over a local Unix socket, requiring only standard user access to the container runtime socket file. No root access is needed unless the socket permissions explicitly restrict access to privileged users.

Can I filter specific resource types in container system df?

The current implementation in SystemDF.swift does not support filtering by resource type via command-line flags. To isolate specific categories (e.g., only volumes), pipe the JSON output to jq and filter the resulting structure: container system df --format json | jq '.[0].volumes'. Future versions may add native filtering capabilities to the CLI.

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