docker-container-top

View documentation for the original command

$ tldr docker top

docker top [OPTIONS] CONTAINER [ps OPTIONS]

CONTAINER
    The name or ID of the running container for which to display processes. This is a mandatory argument.

[ps OPTIONS]
    Optional arguments to pass directly to the `ps` command executed inside the container. These options control the format and columns of the output. For example, `aux` for detailed output or `-ef` for a full format listing. The availability and behavior of these options depend on the `ps` utility installed within the container's image.

The docker top command allows users to view the running processes inside a specific Docker container. It functions similarly to the top or ps command on a Linux host, but operates within the isolated environment of a container. This is crucial for debugging, monitoring, and understanding resource consumption of applications running within containers. It displays process ID (PID), user, CPU usage, memory usage, and the command line that initiated the process, providing insights into the container's operational state. This command is particularly useful for diagnosing issues where a container might be consuming excessive resources or for verifying that expected processes are running correctly.

Container Must Be Running: The command can only display processes for containers that are currently in a running state. If the container is stopped, an error will occur.
`ps` Utility Dependency: `docker top` relies on the `ps` utility being present and executable within the container's file system. Minimalistic base images might not include `ps`, leading to an error or an incomplete output.
Snapshot vs. Real-time: This command provides a snapshot of processes at the moment of execution. For continuous, real-time monitoring of resource usage, `docker stats` is a more appropriate tool.
PID Namespace: The PIDs displayed are specific to the container's PID namespace, meaning PID 1 inside the container is the initial process of that container, not PID 1 of the host system.

The `docker top` command functions by essentially executing the `ps` utility within the target container's isolated environment. This means that the processes listed are those visible from inside the container's perspective, and the columns displayed (e.g., USER, PID, CPU, MEM, COMMAND) are determined by the version and configuration of `ps` installed within that specific container image. The output format and available options are therefore subject to the container's internal `ps` utility.

While `docker top` itself has minimal options, its power comes from passing standard `ps` options directly to the command executed inside the container. Common examples include `docker top my-container aux` for a full listing of processes with user, CPU, and memory, or `docker top my-container -ef` for a standard full-format listing, which can reveal process trees and environmental variables if supported by the container's `ps`.

The command was originally named `docker-container-top` in earlier versions of Docker, clearly indicating its operation on containers. As Docker evolved and its command-line interface was streamlined for better user experience and consistency, it was shortened to `docker top`. This simplification made the command more intuitive and aligned with other top-level Docker commands like `docker ps` and `docker logs`, while maintaining its core functionality of inspecting container processes.

docker ps(1), docker stats(1), ps(1), top(1)