# How to Inspect Container and Image Details Using the container inspect Command

> Learn how to inspect container and image details with the container inspect command. Access low-level JSON data for your containers and images efficiently.

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

---

**The `container inspect` and `container image inspect` commands retrieve low‑level, machine‑readable JSON details about containers and images by querying the container‑apiserver backend via a local Unix-domain socket or HTTP+TLS connection.**

The **apple/container** repository provides a CLI for managing OCI containers and virtual machines on macOS. When you need to examine the internal state of a running container or the metadata of a stored image, the **`container inspect` command** serves as the primary interface for accessing this structured data. It returns comprehensive JSON output describing resource limits, mounts, network interfaces, image manifests, and platform-specific variants.

## How the container inspect Command Works

The `container inspect` family of commands operates by building an **InspectRequest** model and forwarding it to the **container‑apiserver**, the backend service that manages VMs, OCI images, and virtual networking. According to [`Sources/ContainerCLI/Commands/InspectCommand.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCLI/Commands/InspectCommand.swift), the CLI parses arguments and constructs this request object before transmission.

The request travels over a local Unix-domain socket (or HTTP+TLS on macOS) to the server-side handler defined in [`Sources/ContainerServer/Handlers/InspectHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerServer/Handlers/InspectHandler.swift). This handler retrieves the current state from the internal **ContainerRuntime** and **ImageStore** components, then serializes the response using the data models defined in [`Sources/ContainerCore/Models/InspectOutput.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCore/Models/InspectOutput.swift).

### Inspecting Running Containers

To inspect a running container, use `container inspect <container-ids>`. This command asks the apiserver for the current state of each specified container, including resource limits, mounts, network interfaces, PID, and exit code. The CLI prints raw JSON to stdout, which you typically pipe to `jq` for readability.

The official documentation in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 431‑449) provides the exact syntax for this operation.

### Inspecting OCI Images

For image inspection, use `container image inspect <images>`. This performs the same underlying operation on one or more OCI images, returning JSON containing the image manifest, config, layer digests, and platform-specific variant information.

Refer to [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 682‑694) for the detailed command syntax.

## Implementation Details

The inspection flow relies on several key components working together:

- **[`Sources/ContainerCLI/Commands/InspectCommand.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCLI/Commands/InspectCommand.swift)**: Parses `container inspect` arguments and builds the `InspectRequest` model.
- **[`Sources/ContainerCore/Networking/ContainerAPIServerClient.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCore/Networking/ContainerAPIServerClient.swift)**: Sends the request to the apiserver and returns the JSON payload.
- **[`Sources/ContainerServer/Handlers/InspectHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerServer/Handlers/InspectHandler.swift)**: Retrieves container and image state from the runtime and encodes it as JSON.
- **[`Sources/ContainerCore/Models/InspectOutput.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCore/Models/InspectOutput.swift)**: Defines Swift structs that mirror the JSON schema for containers, images, networks, and volumes.

## Practical Examples

Here are runnable examples for common inspection tasks:

```bash

# Show detailed JSON for a running container named "my-web-server"

container inspect my-web-server | jq .

```

```bash

# Inspect multiple containers at once and extract specific fields

container inspect web db cache | jq '.[] | {id, status, resources}'

```

```bash

# Pretty-print an image's manifest and config

container image inspect alpine:3.22 | jq .

```

```bash

# Use --debug to see the raw HTTP request/response for troubleshooting

container inspect --debug my-web-server

```

## Summary

- The **`container inspect` command** provides low-level JSON data about containers, images, networks, and volumes by querying the container‑apiserver.
- **Implementation files** include [`Sources/ContainerCLI/Commands/InspectCommand.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCLI/Commands/InspectCommand.swift) for CLI parsing and [`Sources/ContainerServer/Handlers/InspectHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerServer/Handlers/InspectHandler.swift) for server-side data retrieval.
- **Output format** is pure JSON, enabling programmatic use with tools like `jq`, `yq`, or `gojq`.
- **Debug mode** (`--debug`) exposes raw HTTP request/response diagnostics when the server is unreachable.

## Frequently Asked Questions

### What is the difference between `container inspect` and `container image inspect`?

`container inspect` retrieves runtime state information about running or stopped containers, including resource limits, mounts, and network interfaces. `container image inspect` queries metadata about OCI images stored in the local ImageStore, returning manifest details, layer digests, and configuration data. Both commands use the same underlying `InspectRequest` mechanism but target different resource types.

### How can I filter the JSON output to show only specific fields?

Because the output is pure JSON, you can pipe the command to `jq` or similar tools. For example, `container inspect web | jq '.[] | {id, status, resources}'` extracts only the ID, status, and resources fields from the inspection results. This approach works for both container and image inspections.

### Where does the inspection data originate in the apple/container architecture?

The data comes from the **ContainerRuntime** and **ImageStore** components within the container‑apiserver. When you run an inspect command, the `ContainerAPIServerClient` in [`Sources/ContainerCore/Networking/ContainerAPIServerClient.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCore/Networking/ContainerAPIServerClient.swift) sends the request to the server, where [`InspectHandler.swift`](https://github.com/apple/container/blob/main/InspectHandler.swift) gathers the current state and serializes it using the models defined in [`Sources/ContainerCore/Models/InspectOutput.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCore/Models/InspectOutput.swift).

### How do I troubleshoot when `container inspect` returns an error or fails to connect?

Use the `--debug` flag to expose raw HTTP request and response diagnostics. This shows the exact communication between the CLI and the container‑apiserver, helping identify network issues, authentication problems, or server unavailability. The debug output is particularly useful when the apiserver is unreachable via the Unix-domain socket or HTTP+TLS connection.