# How to List Available Images Using the `container image list` Command > Learn how to list available container images locally using the `container image list` command. Discover OCI images, filter infrastructure images, and sort results easily. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-12 --- **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)](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)](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: ```bash # 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.