1. Overview
Docker provides various options to list and filter containers in different states or even options to customize the list output.
In this tutorial, we’re going to see how we can filter Docker containers in a variety of ways.
2. Listing Containers
In order to list the Docker containers, we can use the “docker ps” or “docker container ls” command. This command provides a variety of ways to list and filter all containers on a particular Docker engine.
Let’s start by listing all the running containers.
2.1. Aliases
As of Docker 1.13, the Docker team regrouped every command to sit under the logical object it’s interacting with. For instance, in order to list Docker containers, in addition to “**docker ps”, we can use the “**docker container list” or even “**docker container ls” command.
All of these three aliases are supporting the same group of options. However, it’s a good idea to adopt the new syntax.
2.2. Running Containers
*If we use the *“**docker container ls” command with no options, it’ll list all the running containers**:
$ docker container ls
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1addfea727b3 mysql:5.6 "docker-en.." 2 seconds ago Up 1 second 0.0.0.0:32801->3306/tcp dazzling_hellman
09c4105cb356 nats:2.1.0-scratch "/nats-…" 17 minutes ago Up 17 minutes 4222/tcp, 6222/tcp, 8222/tcp nats-1
4cf774b9e4a4 redis:5 "docker-…" 30 minutes ago Up 30 minutes 0.0.0.0:32787->6379/tcp redis-2
In this case, we have three running containers so far — MySQL, Nats, and Redis.
2.3. All Containers
By default, the “**docker container ls” command only shows the running containers.
However, if we pass the -a or –all option, it’ll list all (stopped and running) containers:
$ docker container ls -a
CONTAINER ID IMAGE STATUS
1addfea727b3 mysql:5.6 Up 4 hours
32928d81a65f mysql:5.6 Exited (1) 4 hours ago
09c4105cb356 nats:2.1.0-scratch Up 4 hours
16d3c67ebd40 postgres:11 Exited (0) 4 hours ago
4cf774b9e4a4 redis:5 Up 4 hours
We now have two containers that were stopped a few hours ago — MySQL and PostgreSQL.
2.4. Latest Containers
To see the last n Docker containers (both running and stopped), we can use the -n
$ docker container ls -n 2
CONTAINER ID IMAGE STATUS
1addfea727b3 mysql:5.6 Up 4 hours
32928d81a65f mysql:5.6 Exited (1) 4 hours ago
It’s also possible to see the latest container via the -l or –latest option:
$ docker container ls --latest
CONTAINER ID IMAGE STATUS
1addfea727b3 mysql:5.6 Up 4 hours
Of course, we can achieve the same thing with the -n 1 option.
2.5. Disabling Truncation
By default, Docker will truncate the output columns if their value is longer than some threshold. In fact, we already saw the truncated values for the container id.
Even though this is a good feature most of the time, we can disable it using the –no-trunc option:
$ docker container ls --latest --no-trunc
CONTAINER ID COMMAND
1addfea727b38f484a2e0023ed7f47dcb9bbfc6e053f094c349391bb38cb3af7 "docker-entrypoint.sh mysqld"
We can see that the output columns are much more verbose now.
2.6. Quiet Mode
It’s also possible to just see the container id of the containers.
To do this, we can use the -q or –quiet option:
$ docker container ls -q
1addfea727b3
09c4105cb356
4cf774b9e4a4
We can mix and match options and see the full container identifiers:
$ docker container ls --quiet --no-trunc
1addfea727b38f484a2e0023ed7f47dcb9bbfc6e053f094c349391bb38cb3af7
09c4105cb3567ba0070dacf7381b9946165908c819c0841cffaa1855766537c7
443fc0c41710ee3811e72fe5079bf4696b9318e0754c38eeab1c960f5c5a7007
b06cfe3053e521704c67a1902a7302665ae05f66ef592419f32b8c73b2a066fd
4cf774b9e4a487a2ba658de37273994161378cffe7e69fe5c928ad29e6946372
The quiet mode can be especially useful when we’re going to pass a collection of ids to another command.
Here’s a way to force delete all containers:
$ docker container rm -f $(docker container ls -aq)
Of course, these sorts of combinations should be used with extreme caution.
2.7. Container Size
We can see the size of a container and its image on disk via the -s or –size options:
$ docker container ls --latest -s
CONTAINER ID IMAGE SIZE
1addfea727b3 mysql:5.6 2B (virtual 256MB)
The first value (2B) represents the number of bytes that are used for the writable layer of each container. The second value is the image size on disk, which is 256 MB in this case.
2.8. Customized Output
If we’re not happy with the default output format, we can customize the output using the Go templates. All we have to do is pass the desired format to the –format option.
Let’s see this in action:
$ docker container ls --format "{{.ID}} -> Based on {{.Image}}, named {{.Names}}, ({{.Status}})"
1addfea727b3 -> Based on mysql:5.6, named dazzling_hellman, (Up 3 hours)
09c4105cb356 -> Based on nats:2.1.0-scratch, named nats-1, (Up 4 hours)
4cf774b9e4a4 -> Based on redis:5, named redis-2, (Up 4 hours)
Here we’ve used what is basically a templated string in the Go template format. The ID, Image, Names and Status are placeholders, and the rest of the text is rendered as-is.
Moreover, it’s possible to show the columns in a tabular format.
We just have to use the table prefix:
$ docker container ls --format "table {{.ID}}\t{{.Image}}\t{{.Names}}"
CONTAINER ID IMAGE NAMES
1addfea727b3 mysql:5.6 dazzling_hellman
09c4105cb356 nats:2.1.0-scratch nats-1
4cf774b9e4a4 redis:5 redis-2
Let’s take a closer look at the fields we can use in the template string:
- .ID – container id
- .Image – image name and tag
- .Command – command responsible for running this container
- .CreatedAt – container creation time
- .Running – elapsed time since the container has started
- .Ports – port mapping
- .Status – container execution status
- .Size – container and its image disk size
- .Names – container name
- .Labels – all labels assigned to a container
- .Mounts – the volumes for a container
- .Networks – all network names attached to a container
2.9. Advanced Filtering
So far, we only filtered the containers based on running or stopped status. As it turns out, “**docker container ls” offers much more than this rudimentary filtering.
In order to filter the containers, we can use the -f or –filter option.
Here we’re going to filter containers with the exited status:
$ docker container ls --filter "status=exited"
CONTAINER ID IMAGE STATUS
32928d81a65f mysql:5.6 Exited (1) 8 hours ago
16d3c67ebd40 postgres:11 Exited (0) 9 hours ago
Note that we should pass the filter criteria with the key=value format.
If we want to apply multiple filters at the same time, we should pass multiple –filter options.
Let’s go even further and only keep the exited containers with exit status equal to 1:
$ docker container ls --filter "status=exited" --filter "exited=1"
CONTAINER ID IMAGE STATUS
32928d81a65f mysql:5.6 Exited (1) 8 hours ago
As we might expect, only MySQL now matches the filter criteria. The running or stopped are not the only Docker container states.
Let’s say we pause a Docker container:
$ docker container pause redis-2
We can then filter all paused containers:
$ docker container ls --filter "status=paused"
CONTAINER ID IMAGE STATUS
4cf774b9e4a4 redis:5 Up 45 minutes (Paused)
Moreover, we can filter containers by any of the possible statuses — created, restarting, running, removing, paused, exited or dead.
If we know some part of the container name, we can search for it:
$ docker container ls -a --filter "name=pg"
CONTAINER ID IMAGE STATUS
16d3c67ebd40 postgres:11 Exited (0) 9 hours ago
We can also filter the containers based on their base image:
$ docker container ls -a --filter "ancestor=postgres"
CONTAINER ID IMAGE STATUS
16d3c67ebd40 postgres:11 Exited (0) 9 hours ago
Here we’re only listing the containers that are based on the postgres image.
It’s even possible to filter containers based on their creation time.
Let’s only keep the containers that are created before the Nats container:
$ docker container ls --filter "before=nats-1"
CONTAINER ID IMAGE STATUS
4cf774b9e4a4 redis:5 Up 52 minutes (Paused)
On the other hand, we can list all the Docker containers created after the Nats one using the since filter:
$ docker container ls --filter "since=nats-1"
CONTAINER ID IMAGE STATUS
2fdc65a6effb mysql:5.6 Exited (137) 4 days ago
1addfea727b3 postgres:11 Exited (0) 3 days ago
3. Conclusion
In this article, we saw how to list and filter Docker containers using the “docker container ls” command and its useful options.
For a more detailed discussion, it’s always a good idea to check out the official documentation.