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.

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.

Checkpoint: you have recorded the exact name or ID you selected. If docker ps prints no rows, there is no running container for this command to inspect. Start the intended service through its normal deployment process first, because this guide does not prescribe a service start command.

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.

Tip: choose fields that answer one question.

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.

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

Warning: switching context is an operational change to where later Docker commands are sent. Do not run a context-changing command merely to make a copied example work. Confirm the intended endpoint with the person or deployment system responsible for it.

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.

Security warning: if access to the Docker socket is denied, first check whether your account is meant to use Docker. Running the command with sudo requires elevated privileges and changes which Docker configuration and context are in play. Socket access is security-sensitive because it can provide control over the daemon. Ask an administrator to grant the approved access or run the read-only inspection on your behalf, and do not weaken socket permissions as a quick fix.

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.

Tip: the command may also fail if the daemon cannot obtain the process listing from the container's runtime or host environment. Preserve the complete Docker error for the operator responsible for that host.

Done means