# How to View Container Logs with the Apple Container CLI > Easily view container logs with the Apple Container CLI. Stream stdout/stderr using commands like `container logs --follow` for real-time insights. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-25 --- **Use the `container logs` command to stream stdout/stderr from running containers, with options like `--follow`, `--boot`, and `-n` to control output.** The `container` CLI from the [apple/container](https://github.com/apple/container) repository provides the primary interface to inspect output from containers running on macOS. Whether you need to debug application errors or monitor the boot sequence of the underlying virtual machine, the built-in logging commands give you direct access to the container's output streams without manually accessing log files. This guide covers how to view container logs using the native CLI tooling and explains the underlying architecture that streams log data from the service to your terminal. ## How Container Log Streaming Works The `container logs` command does not read static files from disk. Instead, it establishes a real-time connection to the **Container API Service** via XPC to stream log data directly from the container's file descriptor. ### The XPC Communication Layer When you execute `container logs`, the CLI (implemented in [`Sources/ContainerCommands/Container/ContainerLogs.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerLogs.swift)) sends a request to the **ContainerAPIService** (`Sources/Services/ContainerAPIService`). The service opens a file descriptor pointing to the container's log stream and forwards that data back to the CLI through an XPC connection. The file descriptor key is defined in `Sources/Services/ContainerAPIService/Client/XPC+.swift` and referenced in [`ImageServiceXPCKeys.swift`](https://github.com/apple/container/blob/main/ImageServiceXPCKeys.swift). This architecture ensures that you see live output immediately, including both historical buffered lines and new entries as they are generated. ### Log Types and Sources The CLI distinguishes between two distinct log sources: - **Standard I/O (default)**: The combined stdout and stderr produced by the OCI-wrapped application running inside the container. - **Boot Log (`--boot`)**: Messages emitted by the container's init image and the virtual machine boot sequence, useful for debugging startup failures. ## Command Syntax and Options The basic syntax for viewing container logs follows this pattern: ```bash container logs [OPTIONS] CONTAINER ``` The command supports several flags to filter and stream output: - **Default behavior**: Displays all available standard output and error lines from the container's application. - **`--boot`**: Switches the output source to show the VM boot log instead of application logs. - **`-f` or `--follow`**: Streams new log entries continuously, similar to `tail -f`, until you interrupt with Ctrl-C. - **`-n `**: Limits output to the last *N* lines; if omitted, all available lines are printed. ## Practical Examples The following examples demonstrate common patterns for viewing container logs in different scenarios: **1. View the standard output of a running container** ```bash container logs my-web-server ``` **2. Follow the log stream in real time** ```bash container logs --follow my-web-server ``` **3. Show only the last 20 lines** ```bash container logs -n 20 my-web-server ``` **4. View the boot process log instead of application output** ```bash container logs --boot my-web-server ``` **5. Combine options to follow the boot log with line limiting** ```bash container logs --boot --follow -n 50 my-web-server ``` ## Viewing Machine Logs For containers running inside a **container machine**, the CLI provides an analogous command implemented in [`Sources/ContainerCommands/Machine/MachineLogs.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Machine/MachineLogs.swift). The syntax and options remain identical: ```bash container machine logs [OPTIONS] MACHINE_NAME ``` This command accesses the machine-level logs through the same XPC service architecture, allowing you to debug the hypervisor and VM management layer separately from individual container applications. ## Log Storage and Error Handling By default, the `container` CLI does **not** write logs to the macOS unified logging system. Logs exist only as streams accessible while the container runs. However, if you start the container system with the `--log-root` flag, log files are written to the specified directory for persistence. When the service cannot access a container's log stream, it returns an error from [`Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift) (specifically around line 760), which the CLI converts to a user-visible message such as "failed to open container logs." This typically occurs if the container has been removed or if the service connection is interrupted. ## Summary - **Use `container logs`** to access stdout/stderr from running containers via the XPC-based Container API Service. - **Reference key files**: [`ContainerLogs.swift`](https://github.com/apple/container/blob/main/ContainerLogs.swift) for the CLI implementation, [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift) for the server-side log FD handling, and `XPC+.swift` for the underlying communication protocol. - **Stream live output** with `--follow` or inspect boot sequences with `--boot`. - **Limit output** using `-n` to view only recent entries rather than the entire log history. - **Persist logs** by starting the container system with `--log-root` if you need files written to disk. ## Frequently Asked Questions ### What is the difference between standard logs and boot logs? Standard logs show the combined stdout and stderr from your application running inside the container, while boot logs (accessed with `--boot`) display the initialization sequence of the container VM, including messages from the init process and virtual machine startup. Use boot logs when debugging container startup failures before your application begins execution. ### How do I save container logs to a file? The CLI streams logs to stdout by default. To save logs to a file, redirect the output using standard shell redirection: `container logs my-container > container.log`. For persistent log files written by the system itself, start the container infrastructure with `container system start --log-root /path/to/logs`, which stores log files in the specified directory. ### Why do I see "failed to open container logs"? This error originates from [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift) (line 760) when the service cannot open the file descriptor for the container's log stream. This typically happens if the container has been deleted, if the Container API Service is not running, or if the container exited and its log buffers were cleared. Ensure the container is running and the service is active with `container system status`. ### Can I view logs for containers that have already stopped? The ability to view logs for stopped containers depends on whether the container system was started with the `--log-root` option. Without this flag, logs exist only as ephemeral streams and are lost when the container stops. With `--log-root`, log files are preserved on disk and can be inspected using standard Unix tools like `cat` or `tail` from the specified log directory.