19.2.2 Ps CLI Command

docker ps lists the containers currently known to the Docker daemon on the local machine. By default, it shows only containers in the running state. With additional flags, it can display containers in any lifecycle state, filter by specific criteria, and format the output for scripting or monitoring purposes. It is the primary command for getting a quick overview of what is running on a Docker host.

Basic Usage

docker ps

Example output:

CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS          PORTS                  NAMES
3a4b5c6d7e8f   nginx:latest   "/docker-entrypoint…"   2 minutes ago   Up 2 minutes    0.0.0.0:8080->80/tcp   web-server
7f6e5d4c3b2a   postgres:15    "docker-entrypoint.s…"  5 minutes ago   Up 5 minutes    5432/tcp               database

Each row represents one running container. The columns are:

Showing All Containers

By default, stopped, created, and exited containers are hidden. The -a flag shows all containers regardless of state:

docker ps -a

CONTAINER ID   IMAGE          COMMAND    CREATED        STATUS                      PORTS   NAMES
3a4b5c6d7e8f   nginx:latest   "nginx…"   2 min ago      Up 2 minutes                80/tcp  web-server
1b2c3d4e5f6a   ubuntu:22.04   "bash"     1 hour ago     Exited (0) 58 minutes ago           dev-box
9e8d7c6b5a4f   myapp:1.0.0    "./run"    3 hours ago    Exited (1) 3 hours ago              app-test

This is essential when debugging failed containers or when looking for stopped containers to remove.

Showing Only Container IDs

The -q flag returns only the container IDs, one per line, with no headers. This output is designed to be piped into other commands:

docker ps -q

3a4b5c6d7e8f
7f6e5d4c3b2a

Combined with -a:

docker ps -a -q

This is widely used in cleanup operations:

# Stop all running containers
docker stop $(docker ps -q)

# Remove all stopped containers
docker rm $(docker ps -a -q)

Filtering Containers

The -f (or --filter) flag narrows results to containers matching specific conditions. Multiple filters can be combined and are applied as AND conditions.

Filter by Status

docker ps -a -f "status=exited"

Available statuses: created, restarting, running, removing, paused, exited, dead.

Filter by Name

docker ps -f "name=web-server"

The name filter performs a substring match, not an exact match.

Filter by Image

docker ps -a -f "ancestor=nginx:latest"

Shows containers created from the specified image or any of its descendants.

Filter by Label

docker ps -f "label=env=production"

docker ps -f "label=team=backend" -f "label=env=staging"

Filter by Network

docker ps -f "network=my-custom-network"

Filter by Volume

docker ps -f "volume=mydata"

Shows containers that have the named volume mounted.

Displaying the Latest Container

The -l (last) flag shows only the most recently created container regardless of state:

docker ps -l

Displaying N Most Recent Containers

docker ps -n 5

Shows the 5 most recently created containers.

Custom Output Formatting

The --format flag accepts a Go template to control which columns appear and in what format:

docker ps --format "{{.ID}}\t{{.Names}}\t{{.Status}}"

3a4b5c6d7e8f    web-server      Up 2 minutes
7f6e5d4c3b2a    database        Up 5 minutes

Common template fields:

JSON Output

For structured parsing in scripts:

docker ps --format "{{json .}}"

Each line is a JSON object representing one container. Combine with jq for powerful querying:

docker ps --format "{{json .}}" | jq '.Names, .Status'

Showing Full Container IDs

By default, IDs are truncated to 12 characters. The --no-trunc flag shows full IDs:

docker ps --no-trunc

Showing Container Sizes

The -s flag adds a SIZE column that shows the writable layer size and the total size (including the image):

docker ps -s

CONTAINER ID   IMAGE     ...   SIZE
3a4b5c6d7e8f   nginx     ...   1.2kB (virtual 142MB)

The virtual size includes the shared read-only image layers.

Typical Operational Patterns

List all containers with their health check status:

docker ps --format "table {{.Names}}\t{{.Status}}"

Monitor containers in a specific network:

docker ps -f "network=production" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Count running containers:

docker ps -q | wc -l