How to List Containers in Docker

Introduction

Before we begin talking about how to list containers in Docker, let's briefly understand - What is Docker?

Docker is a platform for containerization that enables you to easily create, test, and deploy applications as portable, separate containers that can run almost anywhere.

It is the de facto container deployment standard, and it is an important tool for DevOps engineers and their continuous integration and delivery pipeline.

When working with Docker, it is essential to be able to view and manage the containers running on your system.

In this tutorial, we will provide an introduction to listing containers in Docker. We will also address a few FAQs on how to list containers in Docker.

List Docker Containers

The following is the syntax for the Docker command for listing containers:

docker container ls [options]

Before 1.13, older versions of Docker used a different command to list the containers:

docker ps [options]

In more recent versions of Docker, where the ps command is an alias for container ls, the above command is still supported.

Use the docker container ls command without any options to see a list of the running containers:

docker container ls

Here is how the output will appear:

Output

CONTAINER ID    IMAGE        COMMAND                  CREATED        STATUS        PORTS       NAMES
c8bded53da86    postgres     "docker-entrypoint.s…"   2 hours ago    Up 2 hours    5432/tcp    pg
571c3a115fcf    redis        "docker-entrypoint.s…"   4 hours ago    Up 4 hours    6379/tcp    cache
05ef6d8680ba    nginx        "nginx -g 'daemon of…"   2 hours ago    Up 2 hours    80/tcp      web

The following columns are present in every line of the output:

• Container ID – A distinctive alphanumeric string that specifies each container.
• Image – The Docker image that is used to build the container.
• Command – The command that is executed when container is started.
• Created - The container's creation time.
• Status - The container's status.
• Ports - The ports that the container has published.
• Name - The container's name.

Only the header line is shown if there are no running containers.

The -a, --all option instructs docker container ls to print a list of all containers:

docker container ls -a

Output

CONTAINER ID    IMAGE        COMMAND                  CREATED        STATUS                    PORTS       NAMES
b28cbaa91f15    couchbase    "/entrypoint.sh couc…"   5 hours ago    Exited (0) 3 hours ago                db
c8bded53da86    postgres     "docker-entrypoint.s…"   2 hours ago    Up 2 hours                5432/tcp    pg
571c3a115fcf    redis        "docker-entrypoint.s…"   4 hours ago    Up 4 hours                6379/tcp    cache
05ef6d8680ba    nginx        "nginx -g 'daemon of…"   2 hours ago    Up 2 hours                80/tcp      web

Columns whose length exceeds a predetermined limit are truncated. To prevent truncation, use the --no-trunc option:

docker container ls --no-trunc

Pass the -q, --quiet option to just display the container IDs:

docker container ls -q

Output

c8bded53da86
571c3a115fcf
05ef6d8680ba

You can format the output using a Go template by using the --format option. For example, to print only the names and status of the containers, including the header, type:

docker container ls --format 'table {{.Names}}\t{{.Status}}'

NAMES    STATUS
pg       Up 2 hours
cache    Up 4 hours
web      Up 2 hours

To see the containers' sizes, use the -s, --size option:

docker container ls -s

There will be a column called SIZE next to each line that displays the container size:

Output

CONTAINER ID    IMAGE        COMMAND                  CREATED        STATUS        PORTS       NAMES    SIZE
c8bded53da86    postgres     "docker-entrypoint.s…"   2 hours ago    Up 2 hours    5432/tcp    pg       63B (virtual 394MB)
571c3a115fcf    redis        "docker-entrypoint.s…"   4 hours ago    Up 4 hours    6379/tcp    cache    0B (virtual 98.2MB)
05ef6d8680ba    nginx        "nginx -g 'daemon of…"   2 hours ago    Up 2 hours    80/tcp      web      2B (virtual 126MB)

When the --last, -n option is used, the command will show the n most recent containers, along with all of their states. Use the following command, for instance, to see the most recent two containers created:

docker container ls -n 2

Output

CONTAINER ID    IMAGE        COMMAND                  CREATED        STATUS                    PORTS       NAMES
b28cbaa91f15    couchbase    "/entrypoint.sh couc…"   5 hours ago    Exited (0) 3 hours ago                db
c8bded53da86    postgres     "docker-entrypoint.s…"   2 hours ago    Up 2 hours                5432/tcp    pg

Additionally, you can specify --latest, -l (the same as -n 1) to only list latest created container:

docker container ls -l

You can filter the output based on specific criteria with the --filter, -foption.

Use the following command, for instance, to see only the containers with the status exited:

docker container ls -f "status=exited"

Output

CONTAINER ID    IMAGE        COMMAND                  CREATED        STATUS                    PORTS       NAMES
b28cbaa91f15    couchbase    "/entrypoint.sh couc…"   5 hours ago    Exited (0) 3 hours ago                db

Check out the Docker documentation for a complete list of supported filters.

FAQ's on how to list containers in Docker

Conclusion

Effectively listing containers in Docker is crucial for monitoring and managing containerized applications.

A Docker container is an independent runtime instance of an image. Use the docker container ls command or its alias, docker ps, to list Docker containers.

If you have any suggestions or queries, kindly leave them in the comments section.