# How to View Container System Logs on macOS with the container CLI > Learn how to view container system logs on macOS using the container CLI. Stream stdout, stderr, and VM boot logs directly to your terminal with the container logs command. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-26 --- **Use the `container logs` command to stream stdout, stderr, or VM boot logs directly from the Container API Service to your terminal via XPC.** The `container` command-line interface provides the native method to view container system logs on macOS, offering real-time access to both application output and virtual machine boot sequences. Unlike traditional macOS applications that write to the unified logging system, this tool streams log data directly from the Container API Service through XPC connections. This approach is implemented in the apple/container repository and provides immediate visibility into containerized workloads without intermediate storage. ## Understanding the Log Architecture When you execute a logs command, the CLI establishes an XPC connection to the **Container API Service** (`Sources/Services/ContainerAPIService`). The service opens a file descriptor pointing to the container's log stream—defined in `Sources/Services/ContainerAPIService/Client/XPC+.swift` and [`ImageServiceXPCKeys.swift`](https://github.com/apple/container/blob/main/ImageServiceXPCKeys.swift)—and forwards the data back to the CLI for rendering on STDOUT. Error handling occurs in [`Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift) around line 760, where failures to open the log file descriptor are converted to user-visible error messages. ## Viewing Container Logs The primary implementation resides in [`Sources/ContainerCommands/Container/ContainerLogs.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerLogs.swift), while machine-specific logging is handled in [`Sources/ContainerCommands/Machine/MachineLogs.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Machine/MachineLogs.swift). ### Log Types and Options The command supports several modes for viewing container system logs on macOS: - **Default mode**: Displays the container's standard I/O (stdout and stderr) produced by the OCI-wrapped application. - **`--boot`**: Shows the VM boot log, including messages from the container's init image and the virtual machine boot sequence. - **`-f` / `--follow`**: Streams new log entries continuously, functioning similarly to `tail -f`. - **`-n `**: Limits output to the last N lines; omitting this flag prints all available log history. ### Persistent Log Storage By default, the CLI does not write logs to the macOS unified logging system or disk. To persist logs to files, you must start the container system with `container system start --log-root `, which writes log files under the specified path. ## Practical Code Examples ```bash # View standard output of a running container container logs my-web-server # Follow log stream in real-time (press Ctrl-C to stop) container logs --follow my-web-server # Show only the last 20 lines of output container logs -n 20 my-web-server # View the VM boot log instead of application output container logs --boot my-web-server # Combine options: follow boot logs, limited to last 50 lines container logs --boot --follow -n 50 my-web-server ``` All examples work identically for container machines using `container machine logs `. ## Summary - The `container logs` command is the primary interface to view container system logs on macOS, streaming data via XPC from the Container API Service. - Default output shows application stdout/stderr, while the `--boot` flag displays VM initialization logs. - Use `-f` to follow logs in real-time and `-n` to limit historical output to specific line counts. - Log persistence requires starting the system with `--log-root`; otherwise, logs exist only as streamed data. - Implementation spans [`ContainerLogs.swift`](https://github.com/apple/container/blob/main/ContainerLogs.swift) (CLI), [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift) (XPC service), and `XPC+.swift` (file descriptor handling). ## Frequently Asked Questions ### What is the difference between `container logs` and `container machine logs`? `container logs` (implemented in [`ContainerLogs.swift`](https://github.com/apple/container/blob/main/ContainerLogs.swift)) displays output for a specific container instance, while `container machine logs` (in [`MachineLogs.swift`](https://github.com/apple/container/blob/main/MachineLogs.swift)) shows logs for the underlying virtual machine host. Both use the same XPC architecture to stream logs from the Container API Service, but target different log streams within the container system. ### Why don't container logs appear in the macOS Console application? The container system does not integrate with the macOS unified logging system by default. According to the source implementation, logs are streamed directly from the service to your terminal via XPC without passing through OSLog. To view logs in files that could be opened with Console, start the container system with `container system start --log-root ` to enable file-based logging. ### How do I troubleshoot VM boot failures versus application crashes? Use `container logs --boot ` to view the VM boot sequence, which includes messages from the init image and virtual machine initialization. For application-level errors, use the default `container logs ` without flags to see stdout and stderr from the OCI-wrapped application. The boot log shows system-level initialization, while standard logs show runtime application output. ### What does the error "failed to open container logs" indicate? As implemented in [`ContainersService.swift`](https://github.com/apple/container/blob/main/ContainersService.swift) around line 760, this error occurs when the XPC service cannot open the file descriptor for the container's log stream. This typically means the container is not currently running, the container system is not started, or the log stream has been closed. Ensure the container is active and the system is running with `container system status` before attempting to view logs.