Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 111 ยท Getting Started

Listing and Inspecting

Learn to see what Docker is running: docker ps and its filters, docker inspect with Go templates, top, stats, port and diff, with real output and common pitfalls.

Once you run more than a couple of containers, the first question in every session is the same: what is running, what state is it in, and how was it started? Docker answers all of it from the command line, without any extra tools. A handful of commands cover about 90% of day-to-day questions: docker ps for the list, docker inspect for every detail, docker top and docker stats for what is happening inside, docker port for published ports and docker diff for what changed on disk.

In this lesson you will read the output of each command column by column, learn to filter and reformat it with --filter and --format, and pull single values out of the big JSON document that docker inspect prints. All examples below were run against a small set of containers that we create first.

A few containers to look at

To have something to inspect, start four containers with different fates: a web server that keeps running, a sleeper that also keeps running, a container that exits normally and one that exits with an error. (The names start with demo- here; use any names you like.)

CONSOLE
$ docker run -d --name demo-web -p 127.0.0.1:8080:80 -e GREETING=hello nginx:alpine
890646128b45a135c7f5e270e33e3864aca70beb4111c3a985370dae76a669c1
$ docker run -d --name demo-sleeper alpine sleep 3600
fc800c619150b52efd73e6fab90e32d6469d1c278ebe9535464dfeb15f5f2d2c
$ docker run --name demo-done alpine echo hi
hi
$ docker run --name demo-fail alpine sh -c 'exit 3'

The two -d runs print the full 64-character ID of the new container and return immediately. The other two run in the foreground, finish and leave a stopped container behind (we did not use --rm). Docker keeps stopped containers until you remove them, which is exactly why docker ps -a is useful.

docker ps: what is running

docker ps (the long form is docker container ls, both are the same command) lists running containers:

CONSOLE
$ docker ps
CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                     NAMES
fc800c619150   alpine         "sleep 3600"             10 seconds ago   Up 9 seconds                              demo-sleeper
890646128b45   nginx:alpine   "/docker-entrypoint.โ€ฆ"   13 seconds ago   Up 12 seconds   127.0.0.1:8080->80/tcp    demo-web

Read the columns from left to right:

Column Meaning
CONTAINER ID The first 12 characters of the 64-character ID. Any unique prefix works as an argument to other commands.
IMAGE The image the container was created from, as you typed it.
COMMAND The process Docker started, cut to fit. --no-trunc shows all of it.
CREATED How long ago the container was created (not started).
STATUS Up ... while running; Exited (code) ... when stopped; also Paused, Restarting, or (healthy) / (unhealthy) when a healthcheck exists.
PORTS Published ports as host-address:host-port->container-port/protocol.
NAMES The container name; Docker invents one like quirky_turing if you do not choose.

Notice that the sleeper has an empty PORTS column: it publishes nothing. And 127.0.0.1:8080->80/tcp tells you that only the local machine can reach the web server (publishing ports covers why that matters).

Stopped containers: ps -a

Add -a (all) to include containers in every state:

CONSOLE
$ docker ps -a
CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS                     PORTS                    NAMES
1508716a3019   alpine         "sh -c 'exit 3'"         6 seconds ago    Exited (3) 4 seconds ago                            demo-fail
2b2d2daa5cc8   alpine         "echo hi"                9 seconds ago    Exited (0) 7 seconds ago                            demo-done
fc800c619150   alpine         "sleep 3600"             11 seconds ago   Up 10 seconds                                       demo-sleeper
890646128b45   nginx:alpine   "/docker-entrypoint.โ€ฆ"   14 seconds ago   Up 13 seconds              127.0.0.1:8080->80/tcp   demo-web

The number in Exited (3) is the exit code of the main process: 0 means success, anything else is a failure you should investigate (see exit codes and, later, debugging containers). The newest container is listed first.

Other handy flags:

  • -q prints only IDs, which is perfect for scripting: docker rm $(docker ps -aq --filter status=exited).
  • -n 2 shows the two most recently created containers.
  • -s adds a SIZE column with the size of the writable layer (more on that below).
  • --no-trunc stops Docker from shortening the ID and command.

Filtering with --filter

Instead of piping docker ps into grep, ask Docker to filter for you. --filter key=value can be repeated; different keys combine with AND.

CONSOLE
$ docker ps -a --filter status=exited --format '{{.Names}} {{.Status}}'
demo-fail Exited (3) 7 seconds ago
demo-done Exited (0) 10 seconds ago
$ docker ps -a --filter exited=3 --format '{{.Names}}'
demo-fail
$ docker ps --filter ancestor=alpine --format '{{.Names}}'
demo-sleeper

The most useful filters are name= (a substring or regular expression), status= (created, running, paused, exited, restarting), exited=<code>, ancestor=<image> (containers started from an image, including images derived from it), label= and health=. Run docker ps --help for the complete list.

name= matches anywhere in the name. --filter name=web also matches my-webapp. Anchor it with a regular expression, --filter 'name=^web$', when you need an exact match in a script.

Formatting with --format

The default table is for humans. --format takes a Go template and lets you pick the columns you care about:

CONSOLE
$ docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
NAMES            IMAGE          STATUS
demo-fail        alpine         Exited (3) 6 seconds ago
demo-done        alpine         Exited (0) 9 seconds ago
demo-sleeper     alpine         Up 12 seconds
demo-web         nginx:alpine   Up 15 seconds

Starting the template with table keeps the header and aligns columns; without it you get raw lines, one per container, ideal for scripts. Placeholders include {{.ID}}, {{.Names}}, {{.Image}}, {{.Command}}, {{.CreatedAt}}, {{.Status}}, {{.Ports}}, {{.Labels}}, {{.Size}} and {{.Networks}}. For machine-readable output use --format json, which prints one JSON object per line.

Make your favorite layout permanent by adding a psFormat key to ~/.docker/config.json:

JSON
{
  "psFormat": "table {{.Names}}\\t{{.Image}}\\t{{.Status}}\\t{{.Ports}}"
}

docker inspect: everything about an object

docker ps shows a summary. docker inspect prints the full configuration and state of a container as a JSON array. The first lines look like this:

CONSOLE
$ docker inspect demo-web | head -22
[
    {
        "Id": "890646128b45a135c7f5e270e33e3864aca70beb4111c3a985370dae76a669c1",
        "Created": "2026-10-23T14:12:59.530583061Z",
        "Path": "/docker-entrypoint.sh",
        "Args": [
            "nginx",
            "-g",
            "daemon off;"
        ],
        "State": {
            "Status": "running",
            "Running": true,
            "Paused": false,
            "Restarting": false,
            "OOMKilled": false,
            "Dead": false,
            "Pid": 24829,
            "ExitCode": 0,
            "Error": "",
            "StartedAt": "2026-10-23T14:12:59.936225612Z",
            "FinishedAt": "0001-01-01T00:00:00Z"
        },

The document is hundreds of lines long, which is why you almost always combine it with --format (or -f) to extract one field. The template walks the JSON using dots: .State.Status means "the Status field of State".

CONSOLE
$ docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' demo-fail
exited 3
$ docker inspect -f '{{.Config.Image}}' demo-web
nginx:alpine
$ docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' demo-web
no
$ docker inspect -f '{{.State.OOMKilled}} {{.RestartCount}}' demo-fail
false 0

Things worth knowing about templates:

  • Lists can be looped over with range: {{range .Config.Env}}{{.}}{{"\n"}}{{end}} prints one environment variable per line.
  • Maps with odd keys need index: {{index .Config.Labels "maintainer"}}.
  • json turns any value into JSON, which is the easiest way to see what a nested value looks like: {{json .NetworkSettings.Ports}}.
CONSOLE
$ docker inspect -f '{{json .NetworkSettings.Ports}}' demo-web
{"80/tcp":[{"HostIp":"127.0.0.1","HostPort":"8080"}]}
$ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' demo-web
172.17.0.2
$ docker inspect -f '{{index .Config.Labels "maintainer"}}' demo-web
NGINX Docker Maintainers <docker-maint@nginx.com>

(The IP address depends on your machine, so yours will differ.) The IP address is nested under .NetworkSettings.Networks.<network name>, and because you rarely want to type the network name, range over all networks is the usual trick.

Common fields to remember

Question Template
Is it running? Why did it stop? {{.State.Status}}, {{.State.ExitCode}}, {{.State.Error}}
Was it killed for using too much memory? {{.State.OOMKilled}}
How many times has it restarted? {{.RestartCount}}
Which environment variables are set? {{.Config.Env}}
Which command runs? {{.Config.Cmd}} and {{.Config.Entrypoint}}
Which volumes and bind mounts? {{.Mounts}}
Which image (by ID)? {{.Image}}
Where is the log file? {{.LogPath}}

Inspecting other objects

docker inspect works on any Docker object: containers, images, volumes, networks. When a name could be both a container and an image, say which one you mean with --type:

CONSOLE
$ docker inspect --type image alpine -f '{{.Os}}/{{.Architecture}}'
linux/amd64

A missing object is not a crash, just an error with exit code 1:

CONSOLE
$ docker inspect nosuch
[]
error: no such object: nosuch

docker inspect prints the configuration the container was created with plus live state, not what is "inside" the container's filesystem. Environment variables shown here include secrets passed with -e, and anyone who can run docker inspect can read them. See managing secrets.

docker top: processes inside a container

docker top lists the processes of a container, as seen from the host. It works even when the image has no ps command.

CONSOLE
$ docker top demo-web
UID                 PID                 PPID                C                   STIME               TTY                 TIME                CMD
root                24829               24805               0                   14:12               ?                   00:00:00            nginx: master process nginx -g daemon off;
statd               24941               24829               0                   14:13               ?                   00:00:00            nginx: worker process
statd               24942               24829               0                   14:13               ?                   00:00:00            nginx: worker process
...

The PIDs are host PIDs: the same process has PID 1 inside the container, but a big number outside. The UID column is also resolved on the host, using the host's /etc/passwd, so a container user with ID 101 appears under whatever name ID 101 has on the host (statd on this machine) instead of nginx. That is a good reminder that users are just numbers to the kernel. You can pass ps options after the name: docker top demo-web -o pid,user,comm.

docker stats: live resource usage

docker stats streams CPU, memory, network and disk figures for running containers and refreshes until you press Ctrl+C. For scripts and for documentation, --no-stream prints a single snapshot:

CONSOLE
$ docker stats --no-stream demo-web demo-sleeper
CONTAINER ID   NAME           CPU %     MEM USAGE / LIMIT     MEM %     NET I/O         BLOCK I/O     PIDS
890646128b45   demo-web       0.00%     6.059MiB / 11.63GiB   0.05%     1.63kB / 126B   0B / 12.3kB   7
fc800c619150   demo-sleeper   0.00%     348KiB / 11.63GiB     0.00%     1.49kB / 126B   0B / 0B       1
Column Meaning
CPU % Share of host CPU used. 100% equals one full core, so a busy 4-thread container can show 400%.
MEM USAGE / LIMIT Memory in use and the limit. Without --memory the limit is the whole host (or the VM that Docker Desktop runs in), as here.
NET I/O Bytes received / sent on the container's network.
BLOCK I/O Bytes read from / written to disk.
PIDS Number of processes and threads. A number that grows without end points to a leak.

--format works here too, for example docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.PIDs}}'. Setting limits is the subject of resource limits.

docker port: where is it published?

If you forgot which host port a container uses, ask instead of reading docker ps carefully:

CONSOLE
$ docker port demo-web
80/tcp -> 127.0.0.1:8080
$ docker port demo-web 80/tcp
127.0.0.1:8080

docker diff: what changed on disk

Every container gets a thin writable layer on top of its image. docker diff lists the files that were Added, Changed or Deleted in that layer compared with the image. We made three changes inside the web container and then asked:

CONSOLE
$ docker exec demo-web sh -c 'echo x > /tmp/note.txt; rm /etc/nginx/conf.d/default.conf; touch /var/www.txt'
$ docker diff demo-web
C /etc
C /etc/nginx
C /etc/nginx/conf.d
D /etc/nginx/conf.d/default.conf
C /run
A /run/nginx.pid
C /var
A /var/www.txt
C /var/cache
C /var/cache/nginx
A /var/cache/nginx/scgi_temp
A /var/cache/nginx/uwsgi_temp
A /var/cache/nginx/client_temp
A /var/cache/nginx/fastcgi_temp
A /var/cache/nginx/proxy_temp
C /tmp
A /tmp/note.txt

Our three edits are there (D default.conf, A /var/www.txt, A /tmp/note.txt), but so are files nginx wrote by itself at startup (/run/nginx.pid, the cache directories). Parent directories show as C whenever something inside them changed. docker diff is a quick way to answer "what is this container writing to its own filesystem?", which tells you what should probably become a volume or a read-only mount. The -s flag of docker ps shows the size of that writable layer:

CONSOLE
$ docker ps -s --filter name=demo-web --format 'table {{.Names}}\t{{.Size}}'
NAMES      SIZE
demo-web   86kB (virtual 67.4MB)

The first number is the container's own writable layer (86 kB of changes); "virtual" adds the shared image (about 67 MB here). Ten containers from the same image share that image once, they do not each cost 67 MB.

Other ways to watch

  • docker events prints a live stream of what the daemon does (create, start, exec, die, ...). Add --since 10m or --filter container=demo-web to narrow it. It is handy when something restarts "by itself".
  • docker system df shows how much disk images, containers, volumes and build cache use (the CLI basics covers it).
  • docker logs shows what the program printed; that is the next lesson.

Cleaning up the demo

Stopped containers stay until removed. Remove ours by name (this is also how you should remove containers in practice, not with broad commands):

CONSOLE
$ docker rm -f demo-web demo-sleeper demo-done demo-fail
demo-web
demo-sleeper
demo-done
demo-fail

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command lists containers that have already stopped as well as running ones?

    docker ps shows only running containers. Adding -a (all) includes created, exited and other states. There is no --stopped flag.
  2. 2. A container shows the status 'Exited (137) 5 minutes ago'. What does the number tell you?

    The number in parentheses is the exit code. Zero means success; 137 means the process was killed with signal 9 (128 + 9), often by docker kill or by the out-of-memory killer.
  3. 3. How do you print only the exit code of a container named job?

    docker inspect returns the whole JSON document; a --format Go template such as {{.State.ExitCode}} extracts a single field.
  4. 4. What does a line starting with 'A' in the output of docker diff mean?

    docker diff uses A for added, C for changed and D for deleted, always relative to the image the container was created from.
  5. 5. The process IDs shown by docker top look very large, although the app believes it is PID 1. Why?

    A container's processes are ordinary host processes in their own PID namespace. Inside the namespace the main process is PID 1; the host sees a different, larger number.

Summary

  • docker ps lists running containers; docker ps -a includes stopped ones, and -q prints only IDs for scripts.
  • Use --filter (status, name, exited, ancestor, label, ...) to select containers and --format with a Go template to choose the output; --format json gives machine-readable lines.
  • The STATUS column shows Up ... or Exited (code) ...; a non-zero exit code means the main process failed.
  • docker inspect prints the complete JSON for any object; extract values with --format, use range for lists, index for odd keys and json to see structure.
  • docker top shows the container's processes with host PIDs, docker stats --no-stream gives one snapshot of CPU, memory, network and disk, and docker port shows published ports.
  • docker diff lists files added, changed or deleted in the writable layer, which reveals what should be a volume.
  • Anyone who can run docker inspect can read the environment variables of a container, so do not treat them as secret.

Next: Logs and exec