19.2.2.3 Ps Filter Option

The filter option in docker ps narrows the list of containers to only those matching specific conditions. Without filters, docker ps returns all running containers (or all containers with -a), which can be unmanageable on a busy host with dozens of containers. The -f flag (short for --filter) accepts key-value pairs that Docker evaluates against each container's metadata.

Basic Syntax

docker ps -f "key=value"

Multiple filters can be specified and are applied as AND conditions — a container must match all provided filters to appear in the results:

docker ps -f "key1=value1" -f "key2=value2"

Available Filter Keys

status

Filters by the container's current lifecycle state:

docker ps -a -f "status=exited"
docker ps -a -f "status=running"
docker ps -a -f "status=paused"
docker ps -a -f "status=created"
docker ps -a -f "status=restarting"
docker ps -a -f "status=dead"

The complete list of statuses: created, restarting, running, removing, paused, exited, dead.

name

Filters by container name using a partial match (substring search):

docker ps -f "name=web"

This matches containers named web, web-server, web-proxy, mywebapp, etc. The match is not anchored to the start or end of the name.

To find a container with an exact name, combine with output review or use a precise enough prefix:

docker ps -f "name=^/web-server$"

id

Filters by container ID (partial match):

docker ps -f "id=a1b2c3d4e5f6"

image

Filters containers created from a specific image:

docker ps -f "image=nginx"
docker ps -f "image=nginx:latest"

ancestor

Filters containers created from an image or any image descended from it. Unlike image, which matches the exact image, ancestor also matches containers based on child images:

docker ps -f "ancestor=ubuntu:22.04"

Shows containers from ubuntu:22.04 as well as any custom image that used ubuntu:22.04 as its base.

label

Filters by container labels. Both key-only and key=value forms are supported:

# Any container with the 'env' label, regardless of value
docker ps -f "label=env"

# Containers where env=production
docker ps -f "label=env=production"

Multiple label filters are ANDed:

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

network

Filters containers connected to a specific network:

docker ps -f "network=my-bridge-network"
docker ps -f "network=host"

The value can be a network name or a network ID.

volume

Filters containers that have a specific volume mounted:

docker ps -f "volume=mydata"
docker ps -f "volume=/host/path"

Works with both named volumes and bind mount paths.

publish

Filters containers that publish a specific port:

docker ps -f "publish=80"
docker ps -f "publish=8080/tcp"

expose

Filters containers that expose (not necessarily publish) a port:

docker ps -f "expose=8080"

since

Shows containers created after a specific container:

docker ps -a -f "since=a1b2c3d4e5f6"

before

Shows containers created before a specific container:

docker ps -a -f "before=a1b2c3d4e5f6"

exited

Filters containers that exited with a specific exit code:

# Find containers that failed (non-zero exit)
docker ps -a -f "status=exited" -f "exited=1"

# Find containers killed by OOM or SIGKILL
docker ps -a -f "exited=137"

health

Filters by container health status:

docker ps -f "health=healthy"
docker ps -f "health=unhealthy"
docker ps -f "health=starting"
docker ps -f "health=none"

Combining Filters with -a

Filters work together with -a to search through all container states:

# Find all failed containers
docker ps -a -f "status=exited" -f "exited=1"

# Find all production containers, running or stopped
docker ps -a -f "label=env=production"

Filters in Cleanup Scripts

Filters are particularly powerful in maintenance workflows:

# Remove all containers that exited with an error
docker rm $(docker ps -a -q -f "status=exited" -f "exited=1")

# Stop all running containers in a specific network
docker stop $(docker ps -q -f "network=staging")

# Remove all stopped containers from a specific team
docker rm $(docker ps -a -q -f "status=exited" -f "label=team=devops")

Combining Filters with --format

Filters pair well with --format to produce precise, readable reports:

docker ps -a -f "status=exited" --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"

NAMES          STATUS                        IMAGE
app-test       Exited (0) 55 minutes ago     myapp:1.0.0
app-failed     Exited (1) 23 hours ago       myapp:0.9.0
dev-session    Exited (130) 2 hours ago      ubuntu:22.04

Filter Evaluation Behavior

• Multiple values for the same key are treated as OR: containers matching any of the values are included.
• Different keys are treated as AND: containers must match all key conditions.

Example (OR for same key, AND across different keys):

# (status=exited OR status=created) AND label=env=staging
docker ps -a \
  -f "status=exited" \
  -f "status=created" \
  -f "label=env=staging"

This returns containers that are either exited or created, AND have the staging label.