docker container ls
| Description | List containers |
|---|---|
| Usage | docker container ls [OPTIONS] |
| Aliases | docker container list docker container ps docker ps |
Description
List containers
Options
| Option | Default | Description |
|---|---|---|
-a, --all | Show all containers (default shows just running) | |
-f, --filter | Filter output based on conditions provided | |
--format | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | |
-n, --last | -1 | Show n last created containers (includes all states) |
-l, --latest | Show the latest created container (includes all states) | |
--no-trunc | Don't truncate output | |
-q, --quiet | Only display container IDs | |
-s, --size | Display total file sizes |
Examples
Do not truncate output (--no-trunc)
Running docker ps --no-trunc showing 2 linked containers.
$ docker ps --no-trunc CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ca5534a51dd04bbcebe9b23ba05f389466cf0c190f1f8f182d7eea92a9671d00 ubuntu:24.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp 9ca9747b233100676a48cc7806131586213fa5dab86dd1972d6a8732e3a84a4d crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db Show both running and stopped containers (-a, --all)
The docker ps command only shows running containers by default. To see all containers, use the --all (or -a) flag:
$ docker ps -a docker ps groups exposed ports into a single range if possible. E.g., a container that exposes TCP ports 100, 101, 102 displays 100-102/tcp in the PORTS column.
Show disk usage by container (--size)
The docker ps --size (or -s) command displays two different on-disk-sizes for each container:
$ docker ps --size CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB) 00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB) - The "size" information shows the amount of data (on disk) that is used for the writable layer of each container
- The "virtual size" is the total amount of disk-space used for the read-only image data used by the container and the writable layer.
For more information, refer to the container size on disk section.
Filtering (--filter)
The --filter (or -f) flag format is a key=value pair. If there is more than one filter, then pass multiple flags (e.g. --filter "foo=bar" --filter "bif=baz").
The currently supported filters are:
| Filter | Description |
|---|---|
id | Container's ID |
name | Container's name |
label | An arbitrary string representing either a key or a key-value pair. Expressed as <key> or <key>=<value> |
exited | An integer representing the container's exit code. Only useful with --all. |
status | One of created, restarting, running, removing, paused, exited, or dead |
ancestor | Filters containers which share a given image as an ancestor. Expressed as <image-name>[:<tag>], <image id>, or <image@digest> |
before or since | Filters containers created before or after a given container ID or name |
volume | Filters running containers which have mounted a given volume or bind mount. |
network | Filters running containers connected to a given network. |
publish or expose | Filters containers which publish or expose a given port. Expressed as <port>[/<proto>] or <startport-endport>/[<proto>] |
health | Filters containers based on their healthcheck status. One of starting, healthy, unhealthy or none. |
isolation | Windows daemon only. One of default, process, or hyperv. |
is-task | Filters containers that are a "task" for a service. Boolean option (true or false) |
label
The label filter matches containers based on the presence of a label alone or a label and a value.
The following filter matches containers with the color label regardless of its value.
$ docker ps --filter "label=color" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani The following filter matches containers with the color label with the blue value.
$ docker ps --filter "label=color=blue" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani name
The name filter matches on all or part of a container's name.
The following filter matches all containers with a name containing the nostalgic_stallman string.
$ docker ps --filter "name=nostalgic_stallman" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman You can also filter for a substring in a name as this shows:
$ docker ps --filter "name=nostalgic" CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 715ebfcee040 busybox "top" 3 seconds ago Up 1 second i_am_nostalgic 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley exited
The exited filter matches containers by exist status code. For example, to filter for containers that have exited successfully:
$ docker ps -a --filter 'exited=0' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds Filter by exit signal
You can use a filter to locate containers that exited with status of 137 meaning a SIGKILL(9) killed them.
$ docker ps -a --filter 'exited=137' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande Any of these events result in a 137 status:
- the
initprocess of the container is killed manually docker killkills the container- Docker daemon restarts which kills all running containers
status
The status filter matches containers by status. The possible values for the container status are:
| Status | Description |
|---|---|
created | A container that has never been started. |
running | A running container, started by either docker start or docker run. |
paused | A paused container. See docker pause. |
restarting | A container which is starting due to the designated restart policy for that container. |
exited | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the docker stop command. |
removing | A container which is in the process of being removed. See docker rm. |
dead | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. dead containers cannot be (re)started, only removed. |
For example, to filter for running containers:
$ docker ps --filter status=running CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman To filter for paused containers:
$ docker ps --filter status=paused CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley ancestor
The ancestor filter matches containers based on its image or a descendant of it. The filter supports the following image representation:
imageimage:tagimage:tag@digestshort-idfull-id
If you don't specify a tag, the latest tag is used. For example, to filter for containers that use the latest ubuntu image:
$ docker ps --filter ancestor=ubuntu CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath Match containers based on the ubuntu-c1 image which, in this case, is a child of ubuntu:
$ docker ps --filter ancestor=ubuntu-c1 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace Match containers based on the ubuntu version 24.04 image:
$ docker ps --filter ancestor=ubuntu:24.04 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 82a598284012 ubuntu:24.04 "top" 3 minutes ago Up 3 minutes sleepy_bose The following matches containers based on the layer d0e008c6cf02 or an image that have this layer in its layer stack.
$ docker ps --filter ancestor=d0e008c6cf02 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 82a598284012 ubuntu:24.04 "top" 3 minutes ago Up 3 minutes sleepy_bose Create time
before
The before filter shows only containers created before the container with a given ID or name. For example, having these containers created:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky 4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat Filtering with before would give:
$ docker ps -f before=9c3527ed70ce CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat since
The since filter shows only containers created since the container with a given ID or name. For example, with the same containers as in before filter:
$ docker ps -f since=6e63f6ff38b0 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton volume
The volume filter shows only containers that mount a specific volume or have a volume mounted in a specific path:
$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" CONTAINER ID MOUNTS 9c3527ed70ce remote-volume $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" CONTAINER ID MOUNTS 9c3527ed70ce remote-volume network
The network filter shows only containers that are connected to a network with a given name or ID.
The following filter matches all containers that are connected to a network with a name containing net1.
$ docker run -d --net=net1 --name=test1 ubuntu top $ docker run -d --net=net2 --name=test2 ubuntu top $ docker ps --filter network=net1 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 The network filter matches on both the network's name and ID. The following example shows all containers that are attached to the net1 network, using the network ID as a filter:
$ docker network inspect --format "{{.ID}}" net1 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 $ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 publish and expose
The publish and expose filters show only containers that have published or exposed port with a given port number, port range, and/or protocol. The default protocol is tcp when not specified.
The following filter matches all containers that have published port of 80:
$ docker run -d --publish=80 busybox top $ docker run -d --expose=8080 busybox top $ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen $ docker ps --filter publish=80 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES fc7e477723b7 busybox "top" About a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen The following filter matches all containers that have exposed TCP port in the range of 8000-8080:
$ docker ps --filter expose=8000-8080/tcp CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy The following filter matches all containers that have exposed UDP port 80:
$ docker ps --filter publish=80/udp CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES Format the output (--format)
The formatting option (--format) pretty-prints container output using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|---|---|
.ID | Container ID |
.Image | Image ID |
.Command | Quoted command |
.CreatedAt | Time when the container was created. |
.RunningFor | Elapsed time since the container was started. |
.Ports | Exposed ports. |
.State | Container status (for example; "created", "running", "exited"). |
.Status | Container status with details about duration and health-status. |
.Size | Container disk size. |
.Names | Container names. |
.Labels | All labels assigned to the container. |
.Label | Value of a specific label for this container. For example '{{.Label "com.docker.swarm.cpu"}}' |
.Mounts | Names of the volumes mounted in this container. |
.Networks | Names of the networks attached to this container. |
When using the --format option, the ps command will either output the data exactly as the template declares or, when using the table directive, includes column headers as well.
The following example uses a template without headers and outputs the ID and Command entries separated by a colon (:) for all running containers:
$ docker ps --format "{{.ID}}: {{.Command}}" a87ecb4f327c: /bin/sh -c #(nop) MA 01946d9d34d8: /bin/sh -c #(nop) MA c1d3b0166030: /bin/sh -c yum -y up 41d50ecd2f57: /bin/sh -c #(nop) MA To list all running containers with their labels in a table format you can use:
$ docker ps --format "table {{.ID}}\t{{.Labels}}" CONTAINER ID LABELS a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd 01946d9d34d8 c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd To list all running containers in JSON format, use the json directive:
$ docker ps --format json {"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"}