feat(system): add nerdctl system df

[ekalinin]

Add nerdctl system df, the equivalent of docker system df: the disk space taken by the images,
containers and local volumes of the current namespace, plus the BuildKit build cache.

$ nerdctl system df
TYPE             TOTAL    ACTIVE    SIZE       RECLAIMABLE
Images           17       1         18.25GB    17.26GB (94%)
Containers       3        3         169.2MB    0B (0%)
Local Volumes    4        3         798.6GB    22.62MB (0%)
Build Cache      44       0         0B         0B

The size definitions

The issue was blocked on a question: Docker v29 changed how an image size is computed (#5027), so
what should system df report? The formulas below were derived from moby/moby v29 with the
containerd image store (daemon/disk_usage.go, daemon/containerd/service.go) and docker/cli v29
(cli/command/formatter/disk_usage.go).

Row	TOTAL	ACTIVE	SIZE	RECLAIMABLE
Images	unique, by target digest	with at least one container	deduplicated: every snapshot and every present blob counted once	Σ (Size - SharedSize) of the unreferenced
Containers	all, stopped included	Running / Paused / Restarting	Σ SizeRw (read-write layer only)	Σ SizeRw of the non-active
Local Volumes	all	with at least one container	Σ Size	Σ Size of the unreferenced
Build Cache	all	in use	Σ Size	Σ Size of those neither in use nor shared

• The Images SIZE is not the sum of the image sizes: what images share is counted once, so
  the row reports the space really taken on disk.
• A single image size is its present content plus its unpacked snapshots, the value nerdctl images already shows as DISK USAGE. The two commands agree. Docker sizes an image by walking
  its manifests, so the index listing them is counted in the row total while no single image is
  charged for it: an unused image is never quite 100% reclaimable.
• Deduplicating by target digest is required, not cosmetic: one target can be stored under several
  names (repo:tag, repo@digest, plus the config digest under k8s.io), which would otherwise
  multiply every count and every size.
• An image reports the created of its config, not the local record time, which only says when it
  was pulled or tagged and would show an old image as brand new. For a multi-platform image it is
  the config of the manifest the host platform matcher selects, since the platforms of an index are
  not necessarily built together; the record time stays as the fallback.

Output

-v/--verbose prints the four detail sections with Docker's SHARED SIZE / UNIQUE SIZE columns.

--format also accepts the Docker table TEMPLATE form, e.g. table {{.Type}}\t{{.Size}}: the
literal \t and \n are expanded, the columns get an aligned header, and the labels go through
docker/cli's HeaderFunctions, so table {{lower .Type}} still names the column TYPE. No
nerdctl command supported table TEMPLATE so far, so the helper lives in pkg/formatter for the
others to adopt. Identifiers are shortened for table output only, matching Format.IsTable(), so
that a custom format stays usable to look a resource up.

Notes

• Images, containers and volumes are namespaced, the build cache is not: it comes from the BuildKit
  host of that namespace, and shows as zeros when BuildKit is down, so the shape of the output does
  not depend on which daemons happen to be up.
• Split the way system prune already is: pkg/cmd/system orchestrates, each kind of resource is
  measured by its own package.
• Unit tests cover the shared-size accounting, the reclaimable percentage (the build cache never
  gets one), the summary and verbose rendering, table TEMPLATE, the platform selection of the
  build time, and the parsing of buildctl du. The integration tests run in a private namespace
  and check the counts after a pull, a run and a stop, plus the verbose sections and the three
  output formats; the counts are asserted as a difference from a baseline taken before the setup,
  since docker has no namespaces and its daemon holds whatever the other tests left behind. Only
  the Local Volumes row needs a _linux file, a mount target being written differently on each
  platform, so the rest runs on Windows too.

Closes #3942

[AkihiroSuda]

Please rebase

[Copilot]

Pull request overview

Adds Docker-compatible nerdctl system df reporting for images, containers, volumes, and BuildKit cache.

Changes:

• Implements summary, verbose, JSON, and templated table output.
• Adds per-resource disk-usage accounting and shared-size calculations.
• Adds API types, documentation, unit tests, and integration tests.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/formatter/table_test.go	Tests table-template formatting.
pkg/formatter/common.go	Adds Docker-style table templates.
pkg/containerdutil/content.go	Walks locally present image content.
pkg/cmd/volume/rm.go	Counts volume-container references.
pkg/cmd/volume/df.go	Calculates volume usage.
pkg/cmd/volume/df_test.go	Tests mounted-volume parsing.
pkg/cmd/system/df.go	Orchestrates and renders disk usage.
pkg/cmd/system/df_test.go	Tests formatting and rendering.
pkg/cmd/image/list.go	Counts containers per image.
pkg/cmd/image/df.go	Calculates deduplicated image usage.
pkg/cmd/image/df_test.go	Tests image accounting.
pkg/cmd/container/df.go	Calculates container writable-layer usage.
pkg/cmd/builder/df.go	Calculates BuildKit cache usage.
pkg/cmd/builder/df_test.go	Tests BuildKit parsing and aggregation.
pkg/api/types/system_types.go	Adds system-df options.
pkg/api/types/diskusage_types.go	Defines disk-usage result types.
pkg/api/types/builder_types.go	Adds builder usage options.
docs/command-reference.md	Documents the command.
cmd/nerdctl/system/system.go	Registers system df.
cmd/nerdctl/system/system_df.go	Implements the CLI command.
cmd/nerdctl/system/system_df_test.go	Adds cross-platform integration tests.
cmd/nerdctl/system/system_df_linux_test.go	Tests Linux volume accounting.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ekalinin]

Confirmed. volumeStore.List skips any volume whose rawGet fails and still returns a nil error (pkg/mountutil/volumestore/volumestore.go:219-223), so system df can under-report the volume total.

I would rather not do this one here. List is part of the VolumeStore interface, and its only caller is Volumes() in pkg/cmd/volume/list.go, shared by nerdctl volume ls, system df and shell completion (cmd/nerdctl/completion/completion.go:181). Strictness cannot be a blanket change there - completion has to stay best-effort - so it needs a new opt-in listing mode on the store, plus a decision on what volume ls should report when a volume is unreadable. That is a change to a shared subsystem with its own compatibility surface, and the best-effort behaviour predates this PR.

Proposal: a follow-up PR adding a strict listing mode to the volume store and switching the accounting path to it, keeping this PR scoped to system df. The other two comments in this review are valid and I am fixing them here.

Happy to fold it into this PR instead if maintainers prefer.

[AkihiroSuda]

Needs rebasing