How to use docker container ls command to list containers

Introduction

In this lab, you will learn how to effectively use the docker container ls command (also known as docker ps) to list and manage your Docker containers. You will start by listing only the currently running containers, then expand your view to include all containers, including those that have stopped.

Furthermore, you will explore how to filter the container list based on various criteria such as status and name, allowing you to quickly find specific containers. Finally, you will learn how to display additional information like container size and format the output to suit your needs, providing a comprehensive understanding of your container landscape.

Skills Graph

List running containers

In this step, you will learn how to list running Docker containers. The docker ps command is used to display information about running containers.

First, let's run a simple container that will stay running. We will use the ubuntu image and run a command that keeps the container alive.

docker pull ubuntu
docker run -d ubuntu sleep infinity

The docker pull ubuntu command downloads the ubuntu image from Docker Hub. The docker run -d ubuntu sleep infinity command runs a new container based on the ubuntu image.

• -d runs the container in detached mode, meaning it runs in the background.
• ubuntu is the image name.
• sleep infinity is the command executed inside the container, which keeps the container running indefinitely.

Now, let's list the running containers using the docker ps command.

docker ps

This command will show you a list of all currently running containers. You should see the ubuntu container we just started. The output includes information like the container ID, image, command, creation time, status, ports, and names.

Show all containers including stopped ones

In the previous step, you learned how to list running containers using docker ps. However, docker ps only shows containers that are currently running. To see all containers, including those that have stopped, you need to use the -a flag.

First, let's stop the ubuntu container we started in the previous step. You will need the container ID or name. You can get this from the output of docker ps.

docker stop $(docker ps -q --filter ancestor=ubuntu)

The docker stop command stops a running container.

• $(docker ps -q --filter ancestor=ubuntu) is a command substitution that gets the ID of the running container based on the ubuntu image. The -q flag outputs only the container ID, and --filter ancestor=ubuntu filters by the image name.

Now, let's list all containers, including the stopped one, using docker ps -a.

docker ps -a

This command will display a list of all containers that have been created, regardless of their current state (running, stopped, exited, etc.). You should see the ubuntu container listed, and its status should be "Exited".

Filter containers by status and name

In this step, you will learn how to filter the list of containers based on their status and name using the --filter flag with the docker ps command. This is useful when you have many containers and want to find specific ones.

First, let's start another container, but this time we will give it a specific name.

docker run -d --name my-nginx nginx

The docker run -d --name my-nginx nginx command runs a new container based on the nginx image in detached mode and assigns it the name my-nginx.

• docker pull nginx is not explicitly needed here as docker run will automatically pull the image if it's not available locally.

Now, let's list only the running containers using a filter for the status.

docker ps --filter status=running

This command will show only the containers that are currently in the "running" state. You should see the my-nginx container listed.

Next, let's filter the containers by name.

docker ps -a --filter name=my-nginx

This command will list all containers (including stopped ones, thanks to -a) that have the name my-nginx. You should see the my-nginx container listed with its status.

You can also combine filters. For example, to list running containers with a specific name:

docker ps --filter status=running --filter name=my-nginx

This will show the my-nginx container only if it is currently running.

Display container size and format output

In this step, you will learn how to display the size of containers and format the output of the docker ps command. Knowing the size of your containers can be helpful for managing disk space.

By default, docker ps does not show the container size. To include the size information, you can use the --size flag.

docker ps -a --size

This command will list all containers (running and stopped) and include two columns related to size: SIZE (the size of the container's writable layer) and VIRTUAL SIZE (the total size of the container, including the image layers).

Sometimes, the default output format of docker ps might not be exactly what you need. You can format the output using the --format flag. This flag takes a Go template string.

For example, to display only the container ID, image name, and status, you can use the following command:

docker ps -a --format "{{.ID}}\t{{.Image}}\t{{.Status}}"

In this format string:

• {{.ID}} refers to the container ID.
• {{.Image}} refers to the image name.
• {{.Status}} refers to the container status.
• \t is used for a tab character to separate the columns.

You can also include the size information in the formatted output.

docker ps -a --format "{{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Size}}"

This command will display the container ID, image, status, and size. The {{.Size}} field includes both the writable layer size and the virtual size.

Experiment with different fields in the format string to customize the output according to your needs. Some other useful fields include {{.Names}}, {{.CreatedAt}}, and {{.Ports}}.

Summary

In this lab, you learned how to use the docker ps command to list Docker containers. You started by listing only running containers using docker ps, after first running a simple ubuntu container in detached mode. You then learned how to display all containers, including stopped ones, by adding the -a flag to the docker ps command, after stopping the previously created container.