How to List Available Images Using the `container image list` Command

The container image list command enumerates locally stored OCI images by loading system configuration, retrieving the image catalog through ClientImage.list(), filtering out infrastructure images, sorting results alphabetically, and rendering output in formats ranging from human-readable tables to structured JSON.

The apple/container repository provides a Swift-based CLI for managing container images and systems. When you need to inspect what images are stored locally, the container image list command (aliased as container image ls) serves as the primary interface, implemented in the open-source codebase with robust filtering and formatting capabilities.

Understanding the Implementation

The command logic resides in [Sources/ContainerCommands/Image/ImageList.swift](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImageList.swift), where the ImageList struct defines the execution pipeline. The implementation follows a distinct sequence of operations to transform raw image data into user-friendly output.

Configuration Loading and System Context

When invoked, the command first initializes a ContainerSystemConfig instance to understand system-wide settings. This configuration includes critical parameters such as the builder and init images that the system requires for internal operations. According to the source code, this setup occurs at the beginning of the execution cycle to ensure the command operates within the correct environmental context.

Image Retrieval and Filtering

The command retrieves the complete catalog of stored images via the ClientImage.list() method. However, not all images are displayed to the end user. The implementation specifically filters out infrastructure images—those required for system operation but not intended for general use. This filtering ensures that the output contains only relevant, user-managed images while excluding internal dependencies.

Sorting and Output Generation

After filtering, the command sorts the remaining images alphabetically by their reference names. The output behavior then branches based on user-provided flags:

• Default mode: Renders a human-readable table showing image references and basic metadata
• Quiet mode (--quiet or -q): Outputs only the image reference names, one per line
• Verbose mode (--verbose or -v): Expands each image to show per-platform variants using VerboseImageRow structures, providing detailed information about multi-architecture manifests

The final rendering leverages the shared Output.render helper method to support multiple serialization formats including table, JSON, YAML, and TOML, controlled via the --format flag.

Practical Usage Examples

The [docs/command-reference.md](https://github.com/apple/container/blob/main/docs/command-reference.md) file documents the command syntax and available options. Here are the most common usage patterns:

# Display all images in a human-readable table (default behavior)

container image list

# Use the shorthand alias

container image ls

# Show only image names (useful for scripting)

container image list --quiet
container image ls -q

# Display detailed platform information for multi-arch images

container image list --verbose
container image ls -v

# Output as JSON for programmatic processing

container image list --format json

# Output as YAML

container image list --format yaml

Key Technical Components

The command implementation relies on several critical structures and methods:

• ImageList struct: The main command implementation in Sources/ContainerCommands/Image/ImageList.swift that conforms to the command protocol and defines the execution entry point
• ClientImage.list(): The client method that communicates with the container runtime to retrieve the current image store contents
• Filtering logic: Removes infrastructure images by comparing against system configuration values
• VerboseImageRow: A specialized structure used when the --verbose flag is active to represent individual platform variants of multi-architecture images
• Output.render: A shared utility method that handles the final serialization across different output formats

Summary

• The container image list command provides local OCI image enumeration with the alias container image ls
• Implementation in ImageList.swift loads system configuration, retrieves images via ClientImage.list(), and filters infrastructure images
• Results are sorted alphabetically by reference before formatting
• Output supports multiple modes: quiet (names only), verbose (platform details), and structured formats (JSON, YAML, TOML)
• Documentation in command-reference.md covers all available flags and usage patterns

Frequently Asked Questions

What is the difference between container image list and container image ls?

There is no functional difference between the two commands. container image ls serves as a shorthand alias for container image list, following common CLI conventions found in other container tools. Both commands execute the same ImageList implementation and accept identical flags.

How do I filter the output to show only specific images?

The standard container image list command does not implement client-side filtering flags for specific image names or patterns. To filter results, use the --quiet flag to output only reference names, then pipe the results to standard Unix tools like grep. For example: container image list -q | grep myapp.

Why do some images not appear in the listing?

The command intentionally filters out infrastructure images required for system operation. These internal images support the container runtime and builder functionality but are excluded from standard output to avoid cluttering the user interface. If you need to verify system images, check the system configuration directly rather than using the image list command.

Can I customize the table columns in the default output?

The default table output uses a fixed schema defined in the ImageList implementation. To access specific image attributes, use the --format json flag to output structured data, then process the JSON with tools like jq to select and arrange the specific fields you need for your workflow.

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