List and Filter Docker Containers: A Cheat Sheet

Docker is a fantastic tool for managing containers that provides effortless commands to interact with containers whether running or stopped. This article will help beginners get comfortable with listing and filtering Docker containers.

A container is a self-contained execution environment that shares the host system’s kernel and is (optionally) isolated from other containers in the system.

1. The Cheat Sheet

1.1. List Docker Containers

Here’s a cheat sheet for listing Docker containers:

1.2. Filter Docker Containers

Here’s a cheat sheet for filtering Docker containers:

For more detailed information on these commands and their sample outputs, keep reading this article.

2. Listing Docker Containers

Docker has two sets of commands, ‘docker container ls‘ and ‘docker ps‘, that essentially serve the same purpose for listing Docker containers and exists for historical reasons.

The ‘docker container ls‘ was introduced in Docker 1.13 and is part of the modern and more structured Docker CLI. It follows the convention of using the docker container namespace for container-related operations.

The ‘docker container ls‘ provides additional options for customizing the output format, filtering containers, and more advanced features, so it is recommended for use in modern Docker environments.

2.1. List Only Running Containers

As we continue to run containers over time, we get a lot of them in our system. To find out what is currently running on our host, we can use the 'container ls' command, as follows:

$ docker container ls

CONTAINER ID   IMAGE                              COMMAND                  CREATED         STATUS         PORTS                                         NAMES
56630ce85fd1   confluentinc/cp-kafka:latest       "/etc/confluent/dock…"   2 minutes ago   Up 2 minutes   0.0.0.0:9092->9092/tcp                        broker
909751e3bb4b   confluentinc/cp-zookeeper:latest   "/etc/confluent/dock…"   2 minutes ago   Up 2 minutes   2888/tcp, 3888/tcp, 0.0.0.0:22181->2181/tcp   zookeeper

This command will list all currently running containers.

By default, Docker outputs seven columns with the following meanings:

2.2. List All Containers (including stopped)

If we want to list not just the currently running containers but all containers that are defined on our system, then we can use the -a or --all command-line parameter, as follows.

Notice the redis container is in exited status.

$ docker container ls --all

CONTAINER ID   IMAGE                              COMMAND                  CREATED         STATUS                     PORTS
        NAMES
df08118023d0   redis                              "docker-entrypoint.s…"   3 minutes ago   Exited (0) 2 minutes ago
        spring-boot-docker-compose-redis-1
56630ce85fd1   confluentinc/cp-kafka:latest       "/etc/confluent/dock…"   3 minutes ago   Up 3 minutes               0.0.0.0:9092->9092/tcp
        broker
909751e3bb4b   confluentinc/cp-zookeeper:latest   "/etc/confluent/dock…"   3 minutes ago   Up 3 minutes               2888/tcp, 3888/tcp, 0.0.0.0:22181->2181/tcp   zookeeper

This will list containers in any state, such as created, running, or exited.

2.3. Listing Only the Container IDs

Sometimes listing the containers with complete information can be overwhelming. The 'container ls' command allows flags to limit the information in the command output.

For example, -q or --quiet flag lists the IDs of all containers.

$ docker container ls --quiet

56630ce85fd1
909751e3bb4b

The above command outputs the trimmed container IDs. If we want to list the complete container IDs, we can use the following command:

$ docker container ls --no-trunc

56630ce85fd1758520522cde1e81a7168e41eb1b5582c92b41cd026405b3f599
909751e3bb4ba908cca32e86a92d61a47047830bfade87dda2408fadf5f98513

This can be quite useful to forcefully delete all containers that are currently defined in the system, including the stopped ones.

$ docker container rm --force $(docker container ls --all --quiet)

2.4. Limit the Number of Containers in Output

If we want to list only the latest containers in use rather than scrolling through a mixed list of old and new containers, we can use the -n <number> flag.

$ docker container ls -n 2

This will list containers the latest 4 containers that have been in use. If you want to display only the most recent container only, then use the --latest flag.

$ docker container ls --latest

3. Filtering Docker Containers

Most of the time, we are not interested in the list of all containers. We only want to see a limited number of containers based on some conditions. Let’s explore what options we have.

3.1. Filtering Containers with A Specific Status

The “docker container ls” command offers much more than listing only the running or stopped containers. We can list containers based on pretty much any status the -f or –filter flag.

A docker container can be in the following states: created, restarting, running, removing, paused, exited or dead.

The following command filters the containers with the exited status.

$ docker container ls --filter "status=exited"

CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS                     PORTS     NAMES
df08118023d0   redis     "docker-entrypoint.s…"   5 minutes ago   Exited (0) 5 minutes ago             spring-boot-docker-compose-redis-1

If we want to select mutiple statuses then we should pass multiple <code>–filter</code> options. Docker will list containers that match at least one of the filter conditions.

$ docker container ls --filter "status=exited" --filter "status=paused"

3.2. Filtering Containers By Container/Image Name

If we are not sure about the other attributes of a container we are searching for, then we can try filtering it by its name. The name can be the partial name or the complete name, both will work.

$ docker container ls --filter "name=redis"

This command will list only the containers that have the name “mysql“. This is useful when you have multiple containers running, and you want to quickly find and inspect containers with a specific name

The name filtering will work if we know even the name of the base image name.

$ docker container ls --filter "ancestor=mysql"

After the above command, Docker will list only the containers that have been created from an image with the name “mysql” as their base. This command is helpful when you want to see all containers derived from a specific base image.

4. Advanced Customization of Output

Docker allows you to customize the output of container listings in a way that suits your specific needs. This is achieved using Go templates.

For example, if we only want to display the container ID, image, and status, then we can run the following command.

docker container ls --format "{{.ID}} {{.Image}} {{.Status}}"

56630ce85fd1 confluentinc/cp-kafka:latest Up 7 minutes
909751e3bb4b confluentinc/cp-zookeeper:latest Up 7 minutes

If we want to format the output in a tabular layout then use the table prefix with the desired column names.

docker container ls --format "table {{.ID}}\t{{.Image}}\t{{.Status}}"

CONTAINER ID   IMAGE                              STATUS
56630ce85fd1   confluentinc/cp-kafka:latest       Up 7 minutes
909751e3bb4b   confluentinc/cp-zookeeper:latest   Up 7 minutes

For reference, we can use the following fields 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

5. Conclusion

This Docker tutorial provides a comprehensive guide on how to view and filter Docker containers using various commands and options including customizing the output format and filtering containers based on their status, names, image ancestry, etc.

Happy Learning !!