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

> Learn to view disk usage for containers and volumes using container system df. Inspect consumption with human-readable or machine-parsable output. Get started now.

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

---

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

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

```bash
container system df --format json

```

Example output:

```json
[
  {
    "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`:

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

```

### YAML and Other Formats

Generate YAML for configuration management or documentation:

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

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