How to Use `container system df` for Disk Usage Analysis in Apple's Container Runtime

The container system df command reports disk usage statistics for images, containers, and local volumes with human-readable or machine-readable output formats.

The container system df command is the built-in disk analysis tool in the apple/container repository. It provides a consolidated view of storage consumption across images, running containers, and local volumes, helping administrators identify reclaimable space. Whether you need a quick visual overview or structured data for automation, this command delivers both through its flexible formatting options.

Understanding the Command Architecture

The implementation follows a client-server architecture that separates data retrieval from presentation.

The SystemDF Implementation

In Sources/ContainerCommands/System/SystemDF.swift, the SystemDF struct defines the command using Swift ArgumentParser. The run() method coordinates the entire operation by parsing the --format option (defaulting to table), creating an XPC client to fetch statistics, and rendering output through the appropriate formatter.

Client-Server Communication via XPC

The command retrieves data through ClientDiskUsage defined in Sources/Services/ContainerAPIService/Client/ClientDiskUsage.swift. This client sends a request to the container-API server via the .systemDiskUsage route. The server returns a DiskUsageStats JSON payload—defined in Sources/ContainerPersistence/Measurement+Parse.swift—that the client decodes into Swift models for local processing.

Using container system df for Disk Analysis

The command supports three output formats to accommodate different workflows.

Default Table Output

Without flags, the command displays a human-readable table showing storage metrics for all resource types:

container system df

The diskUsageTable() helper in SystemDF.swift builds a row matrix and passes it to TableOutput—a generic table-rendering utility in Sources/ContainerCommands/TableOutput.swift. The output displays five columns:

• TYPE: Resource category (Images, Containers, Local Volumes)
• TOTAL: Count of all objects
• ACTIVE: Currently in-use objects
• SIZE: Total bytes consumed
• RECLAIMABLE: Deletable bytes with percentage

Example output:

TYPE          TOTAL  ACTIVE  SIZE      RECLAIMABLE
Images        12     3       1.4 GiB   200 MiB (14%)
Containers    8      5       2.1 GiB   500 MiB (24%)
Local Volumes 5      2       3.7 GiB   1.2 GiB (33%)

JSON Output for Scripting

For automation and integration with monitoring tools, use the JSON format to receive raw byte counts:

container system df --format json

[
  {
    "type": "Images",
    "total": 12,
    "active": 3,
    "sizeInBytes": 1503238553,
    "reclaimable": 209715200
  },
  {
    "type": "Containers",
    "total": 8,
    "active": 5,
    "sizeInBytes": 2254857830,
    "reclaimable": 524288000
  },
  {
    "type": "Local Volumes",
    "total": 5,
    "active": 2,
    "sizeInBytes": 3984588800,
    "reclaimable": 1288448000
  }
]

YAML Output for Configuration

YAML format provides human-readable structured data ideal for configuration files:

container system df --format yaml

- type: Images
  total: 12
  active: 3
  sizeInBytes: 1503238553
  reclaimable: 209715200
- type: Containers
  total: 8
  active: 5
  sizeInBytes: 2254857830
  reclaimable: 524288000
- type: Local Volumes
  total: 5
  active: 2
  sizeInBytes: 3984588800
  reclaimable: 1288448000

Parsing the Output Columns

Understanding the metrics requires familiarity with how the source code calculates these values.

The SIZE column displays the total footprint using ByteCountFormatter via the formatSize(_:) helper, converting raw bytes to localized strings like "1.4 GiB". The RECLAIMABLE column shows space that can be freed, calculated by formatReclaimable(_:total:) which computes percentages and caps values at 100% for safety. This prevents display anomalies when reclaimable calculations exceed total size due to overlapping references or shared layers.

Summary

• container system df is the primary command for disk usage analysis in the apple/container runtime.
• The command is implemented in Sources/ContainerCommands/System/SystemDF.swift using the SystemDF struct.
• Data retrieval occurs via XPC through ClientDiskUsage requesting the .systemDiskUsage route.
• Three output formats are available: table (default), json, and yaml via the --format flag.
• Output columns include TYPE, TOTAL, ACTIVE, SIZE, and RECLAIMABLE with human-readable byte formatting.
• The formatReclaimable function caps percentage calculations at 100% to prevent display anomalies.

Frequently Asked Questions

How does container system df calculate reclaimable space?

The formatReclaimable(_:total:) function in SystemDF.swift computes the percentage of reclaimable bytes relative to the total size, capping the result at 100% to ensure safe display values. This calculation reflects data identified by the container runtime as safe to delete without affecting active resources.

Can I filter the output to show only specific resource types?

The base command does not provide built-in filtering flags. To isolate specific resource types like volumes, pipe the table output to standard Unix utilities: container system df --format table | grep Volumes. For programmatic filtering, use the JSON output format and process with tools like jq.

What format does the XPC client use to return disk usage data?

The ClientDiskUsage client in Sources/Services/ContainerAPIService/Client/ClientDiskUsage.swift receives a JSON payload that decodes into the DiskUsageStats model, defined in Sources/ContainerPersistence/Measurement+Parse.swift. This structure contains raw byte counts for total size and reclaimable space across all resource categories.

Is the table output suitable for automated parsing?

While the table format uses ByteCountFormatter for human readability—making it unsuitable for reliable automated parsing—use the --format json option instead. JSON output provides precise sizeInBytes and reclaimable integers without localization or unit variations that complicate scripting.

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