How to List Containers in Docker

Docker is a containerization platform that allows you to quickly build, test, and deploy applications as portable, self-sufficient containers that can run virtually anywhere. It is the de-facto standard for container deployment, and it is an essential tool for DevOps engineers and their continuous integration and delivery pipeline.

In this article, we’ll explain how to list Docker containers.

List Docker Containers #

The Docker command for listing containers takes the following form:

docker container ls [options]

Older Docker versions before 1.13 are using a different command to list the containers:

docker ps [options]

The command above is still supported in newer Docker versions where the ps command is an alias to container ls.

To list the running containers, execute the docker container ls command without any option:

docker container ls

The output will look something like this:

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

Each line of the output includes the following columns:

• Container ID – A unique alphanumeric string that identifies each container.
• Image – The Docker image that is used to create the container.
• Command – The command that is executed when starting the container.
• Created – The creation time of the container.
• Status – The status of the container.
• Ports – The container’s published ports.
• Name – The name of the container.

If there are no running containers, only the header line is displayed.

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

docker container ls -a

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

By default, columns with a length exceeding a specified limit are truncated. Use the --no-trunc option to disable truncation:

docker container ls --no-trunc

To only display the containers’ IDs pass the -q, --quiet option:

docker container ls -q

c8bded53da86
571c3a115fcf
05ef6d8680ba

The --format allows you to format the output using a Go template. For example, to print only the containers’ names and status, including the header, you would run:

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

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

Use the -s, --size option to view the size of the containers:

docker container ls -s

Each line will include a column named SIZE that shows the container size:

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)

The --last, -n option tells the command to display n last created containers, including all states. For example, to view the latest two created containers, you would run:

docker container ls -n 2

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

There is also an option to list only the latest created container --latest , -l which is same as -n 1:

docker container ls -l

The --filter, -f option allows you to filter the output based on certain criteria.

For example, to view only the containers with status exited, you would run:

docker container ls -f "status=exited"

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

For a list of all supported filters, check the Docker documentation

Conclusion #

A Docker container is a standalone runtime instance of an image. To list Docker containers, use the docker container ls command or its alias docker ps.

If you have any questions, please leave a comment below.