Docker ps Tutorial: List Containers with Filters and Custom Formatting

docker ps lists containers. For the complete container workflow, see Container lifecycle.

Syntax

docker ps [options]

docker ps and docker container ls are the same command.

Options

Common --filter conditions:

Examples

The environment has three containers: the running web (nginx) and worker1 (with the team=backend label), and the stopped stopped1.

Running and all containers

$ docker ps
CONTAINER ID   IMAGE               COMMAND                  CREATED         STATUS         PORTS     NAMES
c260b28b0630   alpine:3.23         "sleep 600"              2 seconds ago   Up 2 seconds             worker1
1ec4fdc5c592   nginx:1.30-alpine   "/docker-entrypoint.…"   8 seconds ago   Up 2 seconds   80/tcp    web

$ docker ps -a
CONTAINER ID   IMAGE               COMMAND                  CREATED         STATUS                     PORTS     NAMES
c260b28b0630   alpine:3.23         "sleep 600"              2 seconds ago   Up 2 seconds                         worker1
17b5b9a8c9ce   alpine:3.23         "true"                   3 seconds ago   Exited (0) 2 seconds ago             stopped1
1ec4fdc5c592   nginx:1.30-alpine   "/docker-entrypoint.…"   8 seconds ago   Up 2 seconds               80/tcp    web

$ docker ps -q
c260b28b0630
1ec4fdc5c592

docker ps doesn't list stopped1; it appears only with docker ps -a, with the status Exited (0). -q outputs IDs only, making them easy to pass to other commands.

Filtering

$ docker ps -a --filter status=exited
CONTAINER ID   IMAGE         COMMAND   CREATED         STATUS                     PORTS     NAMES
17b5b9a8c9ce   alpine:3.23   "true"    3 seconds ago   Exited (0) 2 seconds ago             stopped1

$ docker ps --filter name=work
CONTAINER ID   IMAGE         COMMAND       CREATED         STATUS         PORTS     NAMES
c260b28b0630   alpine:3.23   "sleep 600"   2 seconds ago   Up 2 seconds             worker1

$ docker ps --filter label=team=backend
CONTAINER ID   IMAGE         COMMAND       CREATED         STATUS         PORTS     NAMES
c260b28b0630   alpine:3.23   "sleep 600"   2 seconds ago   Up 2 seconds             worker1

Customizing fields

$ docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"
NAMES     IMAGE               STATUS
worker1   alpine:3.23         Up 2 seconds
web       nginx:1.30-alpine   Up 3 seconds

table adds a header row, and \t (Tab) separates the fields. Common fields include .ID, .Names, .Image, .Status, .Ports, .CreatedAt, .Labels, and .Size. Use --format json to output JSON.

Container sizes and the latest container

$ docker ps -s
CONTAINER ID   IMAGE               COMMAND                  CREATED         STATUS         PORTS     NAMES     SIZE
c260b28b0630   alpine:3.23         "sleep 600"              3 seconds ago   Up 2 seconds             worker1   4.1kB (virtual 9.1MB)
1ec4fdc5c592   nginx:1.30-alpine   "/docker-entrypoint.…"   9 seconds ago   Up 3 seconds   80/tcp    web       86kB (virtual 66.8MB)

$ docker ps -n 1
CONTAINER ID   IMAGE         COMMAND       CREATED         STATUS         PORTS     NAMES
c260b28b0630   alpine:3.23   "sleep 600"   3 seconds ago   Up 2 seconds             worker1

• The first number in SIZE is the size of the container's writable layer; virtual includes the image. The nginx container wrote some temporary files on startup, so its size is 86kB.
• -n 1 shows only the most recently created container.

Batch processing: remove all stopped containers

$ docker rm $(docker ps -aq --filter status=exited)
17b5b9a8c9ce

$(...) runs the command inside first, then passes its result (the IDs of all stopped containers) as arguments to docker rm. You can get the same result with docker container prune (see Freeing disk space).

PowerShell also supports the $(...) syntax; Windows CMD doesn't, so use docker container prune instead.

Related chapters

• Container lifecycle
• docker inspect: View detailed information about a single container
• docker compose commands: docker compose ps

Exercises

Exercise: List all containers created from nginx:1.30-alpine, including stopped ones, and show only their names and statuses.

docker ps -a --filter ancestor=nginx:1.30-alpine --format "table {{.Names}}\t{{.Status}}"

Updated October 14, 2026