apptainer-inspect

Show the labels of an image (default)

$ apptainer inspect [path/to/image.sif]

$ apptainer inspect [[-d|--deffile]] [path/to/image.sif]

$ apptainer inspect [[-r|--runscript]] [path/to/image.sif]

$ apptainer inspect [[-e|--environment]] [path/to/image.sif]

$ apptainer inspect --list-apps [path/to/image.sif]

$ apptainer inspect --all [path/to/image.sif]

$ apptainer inspect [[-h|--help]]

apptainer inspect [options...] <image>

--app <appname>
    Show metadata for specific application in image

--csv
    Output in CSV format for tabular data

--dir
    Dump directory metadata from image

--dump-labels
    Print all image labels to stdout

--human-readable
    Show sizes in human-readable units (e.g., GB)

--json
    Output structured data in JSON format

--label <label>
    Display value of specific label

--remote
    Inspect remote image via Library API

--section <section>
    Inspect specific section: deffile, labels, runtime, execution

-h, --help
    Display command help

--debug
    Enable debug output (global option)

--quiet
    Suppress non-essential output (global)

-v, --verbose
    Increase verbosity (global)

The apptainer inspect command retrieves and displays embedded metadata from Apptainer (formerly Singularity) container images, primarily in SIF format. This includes labels set during build, the original definition file, runtime configuration, and execution details.

It enables users to examine container properties without running the image, essential for HPC workflows, auditing images, verifying builds, and scripting. Output can be formatted as human-readable text, JSON, or CSV for parsing.

Specify sections like deffile (build recipe), labels (key-value metadata), runtime, or execution with --section. Dump all labels or query specific ones. For multi-app images, target apps with --app. Supports local files, directories, or remote library images via --remote and the Apptainer Library API, avoiding full downloads.

Ideal for compliance checks, debugging pull failures, or integrating into CI/CD pipelines. Requires Apptainer installed; works on unprivileged systems.

Only supports SIF images or writable sandboxes; remote inspection requires configured Library endpoint. Encrypted images need apptainer unlock options. No support for OCI formats natively.

deffile: Original %post/%run etc. definition file contents.
labels: Build-time key-value pairs (e.g., org.label-schema.version).
runtime: Bind mounts, env vars, GPU config.
execution: Entry point, shebang details.

With --json: {"data": {...}, "attributes": {...}} – includes image ID, size, apps array for automation.

Derived from Singularity inspect (introduced ~2016 in v2.4 for metadata querying). Evolved in Singularity 3.x with JSON/sections. Renamed apptainer inspect in 2021 (v1.0) during Sylabs-to-Linux Foundation transition, adding remote API support and structured outputs for HPC/cloud use.

apptainer(1), singularity(1), podman-inspect(1)