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>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
443fc0c41710        rabbitmq:3.7         "docker-…"      17 minutes ago      Up 17 minutes       4369/tcp, 5671-5672/tcp, 25672/tcp   rabbit-1
b06cfe3053e5        postgres:11          "docker-…"      29 minutes ago      Up 29 minutes>5432/tcp              pg-2
4cf774b9e4a4        redis:5              "docker-…"      30 minutes ago      Up 30 minutes>6379/tcp              redis-2

We have five running containers so far — Nats, RabbitMQ, PostgreSQL, MySQL and Redis.

By default, the output shows several details about each running container:

  • CONTAINER ID is the container unique identifier. This identifier is the truncated version of a pretty long SHA-256 hash.
  • IMAGE is the container image name and its tag separated by a colon, such as postgres:11.
  • COMMAND is the command responsible for running the container.
  • CREATED shows when the container was created.
  • STATUS shows the container status. As mentioned above, all these containers are running.
  • PORTS shows the port mappings between the host machine and inside the container. For instance, the>5432/tcp means that port 32789 in the host is mapped to port 5432 inside the container. Also, we can see that we didn’t map any port for the Nats container — 4222/tcp, 6222/tcp, 8222/tcp.
  • NAMES represents the human-readable name of the Docker container, such as pg-2.

By now, we should know about the meaning of each column. So, from now on, we’ll only show a subset of these columns for the sake of brevity.

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
443fc0c41710        rabbitmq:3.7         Up 4 hours
b06cfe3053e5        postgres:11          Up 4 hours
16d3c67ebd40        postgres:11          Exited (0) 4 hours ago
4cf774b9e4a4        redis:5              Up 4 hours
99c537a3dd86        redis:5              Exited (0) 4 hours ago

We now have three containers that were stopped a few hours ago — Redis, MySQL and PostgreSQL.

2.4. Latest Containers

To see the last n Docker containers (both running and stopped), we can use the -n <number> or –last <number> option:

$ 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

We can mix and match options and see the full container identifiers:

$ docker container ls --quiet --no-trunc

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)
443fc0c41710 -> Based on rabbitmq:3.7, named rabbit-1, (Up 4 hours)
b06cfe3053e5 -> Based on postgres:11, named pg-2, (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 IDImageNames 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
443fc0c41710        rabbitmq:3.7         rabbit-1
b06cfe3053e5        postgres:11          pg-2
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
99c537a3dd86        redis:5             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
b06cfe3053e5        postgres:11         Up 18 minutes
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
b06cfe3053e5        postgres:11         Up 28 minutes
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
443fc0c41710        rabbitmq:3.7        Up 52 minutes
b06cfe3053e5        postgres:11         Up 52 minutes
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.

Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.