See What a Container Is Running with docker container top

A container is misbehaving and you want to know what is actually running inside it, so you reach for docker container top. You will list the processes in a running container, add a few ps display options when needed, and tell a missing-container error from a process-listing failure. Allow about ten minutes.

• You need: the Docker CLI and access to a Docker daemon with a running container.
• Versions: the examples use Docker Community Edition CLI 29.8.1, installed here as package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble.

The local manual describes docker container top as displaying running processes, and says the displayed information is from the host's point of view. Keep that in mind: it explains most of the surprises below.

1. Choose a running container

List the running containers. This is a read-only command and normally needs no elevated privileges when your user can access Docker:

$ docker ps --format 'table {{.ID}}\t{{.Names}}\t{{.Image}}'
CONTAINER ID   NAMES       IMAGE
abc123def456   web         web:latest

Use either the displayed name or ID as the CONTAINER argument. Prefer an ID copied from a fresh docker ps result when containers are recreated by a deployment. A name or ID from an older result can stop working even if a replacement container looks similar.

2. Display the default process list

Run top with the selected container:

$ docker container top CONTAINER_NAME
PID      TTY       STAT       TIME         COMMAND
16623    ?         Ss         0:00         sleep 99999

Replace CONTAINER_NAME with a real value such as web. The exact rows depend on the container image and its current workload. A successful result commonly includes a header followed by process IDs, terminal and state information, CPU time, and a command. It is a snapshot, not a continuously refreshing monitor.

You can use the shorter equivalent form:

$ docker top CONTAINER_NAME

The two spellings invoke the same Docker operation. Use the longer form in runbooks if it makes the command's purpose clearer to people scanning a procedure.

3. Ask ps for fields that answer your question

Arguments after the container are passed to the host's ps command. For example, request parent IDs, process state, elapsed time and the full command:

$ docker container top CONTAINER_NAME -o pid,ppid,stat,etime,cmd
PID                 PPID                STAT                ELAPSED             CMD
980102              980077              Ssl                 18:09:35            webd

The available options are those accepted by the relevant Linux ps implementation, so output headings and column widths can differ between hosts. The local Docker manual gives -x as a simple example:

$ docker container top CONTAINER_NAME -x

Do not treat -x as a Docker-specific switch. It is a ps option placed after the container argument. Check the host's ps manual when you need a format that is portable across distributions, or when a particular option is rejected.

• pid identifies the process.
• ppid shows its parent.
• stat gives its state.
• cmd shows the command as reported by the host.

Avoid pasting a long collection of formatting flags into an incident note before checking that the target host supports them.

4. Read the result from the host's point of view

docker container top asks the daemon to obtain a process listing for the container. The local manual explicitly frames all displayed information from the host's point of view. That matters when you compare a container's process IDs with host tools such as ps, or when you investigate namespaces.

• A host PID is not the in-container PID. Do not infer that it is the process number an application sees inside its PID namespace. A container may show a process with a host-side ID that differs from its in-container PID.
• The command column is a host-side report. It is evidence of what the listing returned, not a promise that every shell expansion or argument is reconstructed exactly as typed.
• It is read-only. This command does not change the container, stop a process, enter its shell, or alter its configuration.
• It is a snapshot. It is fine for a quick look, but it does not replace application logs or a long-running metrics tool when you need history.

5. Diagnose the common failures

If Docker reports that there is no such container, refresh the selection:

$ docker ps --format '{{.ID}} {{.Names}}'
$ docker container top FRESH_ID_OR_NAME

This usually means the container was removed or recreated, the name was mistyped, or the CLI is using a different Docker context. Check the context without changing it:

$ docker context show
default

If Docker reports that the container is not running, inspect all containers:

$ docker ps -a --filter name=CONTAINER_NAME --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'

A stopped container has no running process list for this command. Starting it may trigger application work or service traffic, so use the container's documented recovery procedure rather than adding sudo or an ad hoc docker start.

If a ps option fails, remove the extra options and retry the basic command. Then consult ps --help or the local ps(1) manual and add one verified option at a time.