Inspect a Running Container with docker top

A container with no shell still needs a process check sometimes, and docker top gets you a live list without touching the workload. You will use it to get a point-in-time process listing from a running container, then narrow the columns when the default output is too wide. The command only observes the container. It does not start, stop, pause or kill anything.

Allow about five minutes. You need Docker CLI access and permission to query the Docker daemon. The examples use a placeholder container called CONTAINER_NAME; replace it with a name or ID from your own host.

1. Check that the target is running

docker top is for a running container. List running containers and copy an exact name or ID:

$ docker ps --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'

Expected output has one row per running container:

CONTAINER ID   NAMES             STATUS
8a1b2c3d4e5f   CONTAINER_NAME   Up 12 minutes

If the target is not listed, it is stopped, paused, or you have selected the wrong Docker context. Check all containers, including stopped ones, with docker ps -a. Do not start a production container merely to obtain a process listing: confirm its expected service behaviour and maintenance window first.

Checkpoint: target selected

You should now have a running container name or ID. If you are returning later, resume at step 2 rather than repeating commands that change container state.

2. Show the default process listing

Run the short command:

$ docker top CONTAINER_NAME

Docker asks the daemon for the processes visible in that container's process namespace and prints the result using the host's ps implementation. A typical Linux result looks like this:

UID        PID       PPID      C  STIME  TTY  TIME     CMD
10001      3557359   3557336   0  08:40  ?    00:00:03 /usr/local/bin/example

The precise columns and values depend on the host ps and the processes present at the instant of the query. A PID is meaningful in the displayed namespace, so do not assume it is the same number you would see from a host-wide ps command. The output is a snapshot, not a live refresh and not a CPU or memory monitor.

3. Request only useful columns

The syntax after the container is passed as ps options. For portable, readable columns on a Linux host, use the BSD-style -o form:

$ docker top CONTAINER_NAME -o pid,ppid,user,stat,comm

For example:

PID       PPID      USER     STAT  COMMAND
3557359   3557336   10001    Ssl   example

Use column names accepted by the host ps, not Docker options. docker top has no container-management flags in its synopsis. If you need the complete command line rather than the executable name, try args or command in the -o list, subject to the installed ps implementation:

$ docker top CONTAINER_NAME -o pid,ppid,user,stat,args

Verify the exact format on the same machine with ps -o pid,ppid,user,stat,comm or ps -o pid,ppid,user,stat,args. This is a local check only; it does not inspect the container.

Checkpoint: output is reproducible

Run the chosen command twice if you are troubleshooting a short-lived process. Differences may simply mean a process started or exited between snapshots. Save the command and its output with the incident notes if another operator needs to reproduce it.

4. Handle common failures without changing state

A name or ID error usually means the target is misspelled, belongs to another Docker context, or no longer exists. Re-run docker ps -a, then check the active context with:

$ docker context show

A message that the container is not running means docker top cannot provide a live process list. Inspect its recorded state and exit code without starting it:

$ docker inspect --format '{{.State.Status}} exit={{.State.ExitCode}}' CONTAINER_NAME

A daemon connection or permission error is an access problem, not a reason to add sudo blindly. First check the Docker client context and daemon status according to your host's operating procedure. If your account normally requires elevated access, use the approved administrative path. Adding yourself to the docker group grants broad control over the host, so treat that as a security decision rather than a quick workaround.

If the command succeeds but shows no rows, the container may have no currently visible processes, or its process namespace may differ from what you expected. Compare the container status and configuration with docker inspect. Do not infer that the service is healthy from a non-empty listing; use the service's own health check, logs, or application probe as appropriate.

5. Know what this command cannot tell you

docker top reports processes and selected ps fields. It does not show a continuous CPU or memory graph, container resource limits, open files, network connections, or application logs. Use a tool that measures the question you are asking: for example, docker stats CONTAINER_NAME for live resource counters, docker logs CONTAINER_NAME for container output, and docker inspect CONTAINER_NAME for configuration and state.

Those commands are observations too, but their output can contain secrets such as environment values, command-line arguments, or application data. Redact sensitive output before putting it in a ticket or sharing it outside the operations team.

Done means