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

> Analyze disk usage in Apple's container runtime with the `container system df` command. Get human-readable or machine-readable stats for images, containers, and volumes.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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](https://github.com/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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:

```bash
container system df

```

The `diskUsageTable()` helper in [`SystemDF.swift`](https://github.com/apple/container/blob/main/SystemDF.swift) builds a row matrix and passes it to `TableOutput`—a generic table-rendering utility in [`Sources/ContainerCommands/TableOutput.swift`](https://github.com/apple/container/blob/main/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:

```bash
container system df --format json

```

```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:

```bash
container system df --format yaml

```

```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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.