docker-top

Display the running processes of a container

$ docker top [container]

$ docker top --help

docker top [OPTIONS] CONTAINER [ps OPTIONS]

CONTAINER
    The name or ID of the running container whose processes you want to display.
This parameter is mandatory.

ps OPTIONS
    Additional options that are passed directly to the ps command executed within the container.
These options allow you to customize the output format and content, just as you would with the standard Linux ps command (e.g., aux, -ef, -o pid,comm,args).

The docker top command provides a powerful way to inspect the processes actively running within a specified Docker container. It functions similarly to the ps command on a traditional Linux host, but its scope is limited to the isolated environment of a single container.

When invoked, docker top queries the container's process namespace and reports details such as the process ID (PID), user (USER), CPU usage (%CPU), memory usage (%MEM), start time (START), and the full command (COMMAND) being executed.

This command is invaluable for debugging, understanding the runtime behavior of applications within containers, and verifying that expected processes are indeed active. Unlike the host's top command, docker top provides a static snapshot of processes at the time of invocation rather than a continuously updating view. For docker top to function, the target container must be in a running state, and typically, the ps utility must be available within the container's filesystem for Docker to execute it internally.

The target container must be in a running state for docker top to retrieve process information.
The ps utility must be present and executable inside the container's filesystem for this command to work effectively. Minimal base images might sometimes lack this utility.
The PIDs displayed are those within the container's isolated PID namespace, not the PIDs on the host system.
docker top provides a snapshot of processes at a given moment; it does not offer a continuous, real-time update like the host's top command. For real-time resource monitoring, consider docker stats.

By default, docker top typically displays columns similar to ps -ef or ps aux, including UID (User ID), PID (Process ID within the container), PPID (Parent Process ID), C (CPU utilization), STIME (Start Time), TTY (Controlling Terminal), TIME (Cumulative CPU time), and CMD (Command executed).

You can pass standard ps options to docker top to tailor the output. For example, docker top my_container aux will show all processes belonging to all users with user-oriented output, while docker top my_container -o pid,comm,args will display only the PID, command name, and full arguments list. This flexibility is crucial for precise debugging.

The docker top command has been a fundamental part of the Docker CLI since its early versions, reflecting the core need to inspect the contents and behavior of running containers. It was designed to offer a familiar ps-like interface for containerized processes, fitting seamlessly into the Docker ecosystem's approach to container management and debugging. Its functionality has remained largely consistent, adapting as Docker's underlying container technology evolved.

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