How to use docker container ls command to list and filter 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 all currently running containers and then expand to include stopped containers.

Furthermore, you will explore how to filter the container list based on various criteria like status and name, and learn how to format the output to display only the specific information you need. Finally, you will discover how to quickly check the disk usage of your containers.

Skills Graph

List all running containers

In this step, you will learn how to list all currently running Docker containers. This is a fundamental command for managing your containers and understanding what is active on your system.

First, let's pull a simple image that we can use to run a container. We will use the hello-world image, which is a very small image designed to test your Docker installation.

docker pull hello-world

You should see output indicating that the image is being pulled and extracted.

Now, let's run a container using this image. The docker run command creates and starts a new container.

docker run hello-world

This command will run the hello-world container. The container will print a message and then exit. Even though it exits, it is still considered a container that exists on your system, just not running.

To see only the containers that are currently running, you use the docker ps command.

docker ps

Since the hello-world container exited immediately after running, the docker ps command will likely show no output under the "CONTAINER ID", "IMAGE", "COMMAND", etc. columns, because there are no containers currently running.

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

docker pull ubuntu

Now, run an Ubuntu container that stays running by executing the sleep infinity command. The -d flag runs the container in detached mode (in the background).

docker run -d ubuntu sleep infinity

You will see a long string of characters, which is the container ID. This indicates that the container has been started in the background.

Now, run docker ps again to see the running container.

docker ps

This time, you should see output listing the Ubuntu container you just started. The output includes information like the container ID, the image used, the command being run, when it was created, its status, ports, and a randomly generated name.

The docker ps command is essential for quickly checking which containers are active and consuming resources on your system.

Show all containers including stopped ones

In the previous step, you learned how to list only the running containers using docker ps. However, sometimes you need to see all containers that exist on your system, including those that have stopped. This is useful for cleaning up old containers or inspecting containers that have exited with an error.

To list all containers, both running and stopped, you use the docker ps command with the -a flag. The -a stands for "all".

Let's try this command now.

docker ps -a

You should see a list that includes the running Ubuntu container from the previous step, as well as the hello-world container that exited after running. The "STATUS" column will show whether a container is "Up" (running) or "Exited".

The output provides the same information as docker ps (container ID, image, command, creation time, status, ports, and name), but for all containers, regardless of their current state.

This command is very helpful for getting a complete overview of all containers on your system. You can see which containers have been created, even if they are not currently active.

Filter containers by status and name

In this step, you will learn how to filter the list of containers based on their status or name. This is very useful when you have many containers and only want to see a specific subset.

The docker ps command supports a --filter flag that allows you to specify criteria for listing containers.

Let's start by listing only the running containers using a filter. The status of a running container is running.

docker ps --filter "status=running"

This command should show the same output as docker ps from Step 1, listing only the Ubuntu container that is currently running.

Now, let's filter for containers that have exited. The status for an exited container is exited. Remember to include the -a flag to see all containers, otherwise, the filter won't find exited containers if they are not listed by default.

docker ps -a --filter "status=exited"

This command should show the hello-world container that you ran in Step 1, as its status is "Exited".

You can also filter by the name of the container. When you run a container without specifying a name using the --name flag, Docker assigns a random name. You can find the name of your running Ubuntu container by running docker ps. Look at the "NAMES" column.

Let's say the name of your Ubuntu container is something like agitated_hoover. You can filter by this name:

docker ps -a --filter "name=agitated_hoover"

Replace agitated_hoover with the actual name of your Ubuntu container. This command will list the container with that specific name, regardless of its status (though in this case, it should be running).

You can combine filters as well. For example, to find a running container with a specific name:

docker ps --filter "status=running" --filter "name=agitated_hoover"

Again, replace agitated_hoover with your container's name.

Filtering is a powerful way to manage and inspect your containers, especially in environments with many containers.

Format the output to show specific information

In this step, you will learn how to customize the output of the docker ps command to show only the information you need. This is particularly useful when scripting or when you want a concise view of your containers.

The docker ps command supports a --format flag that allows you to specify the output format using Go template syntax.

Let's start by listing only the container IDs of all containers.

docker ps -a --format "{{.ID}}"

This command will output a list of container IDs, one per line, for all containers (running and stopped). The {{.ID}} is a Go template placeholder that represents the container ID.

Now, let's list the container ID and the image name, separated by a tab.

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

You should see output like [container ID] [image name] for each container. \t represents a tab character in the Go template.

You can include other fields as well. Here are some common fields you can use:

• .ID: Container ID
• .Image: Image name
• .Command: Command being executed
• .CreatedAt: Time of creation
• .Status: Container status
• .Ports: Exposed ports
• .Names: Container names

Let's list the container name and its status.

docker ps -a --format "{{.Names}}: {{.Status}}"

This will output something like [container name]: [status] for each container.

You can also use the table format to get a more readable output with headers, similar to the default output but with only the columns you specify.

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

This command will display a table with columns for ID, Image, Names, and Status for all containers.

Formatting the output gives you fine-grained control over the information displayed by docker ps, making it easier to parse and use in scripts or for specific reporting needs.

Show disk usage of containers

In this final step, you will learn how to view the disk space used by your Docker containers, images, and volumes. This is important for monitoring your system's resources and identifying where disk space is being consumed by Docker.

The docker system df command provides a summary of the disk space used by Docker objects. The df stands for "disk free", similar to the standard Linux command.

Let's run the command to see the disk usage.

docker system df

The output will show a summary including:

• Images: The total size of all Docker images on your system.
• Containers: The total size of the writable layer for all containers. This is the space used by changes made within the container's filesystem.
• Local Volumes: The total size of all local volumes. Volumes are used for persistent data storage.
• Build Cache: The size of the build cache used during image builds.

You will see columns like "Total", "Active", "Size", and "Reclaimable".

• Total: The total number or size of the objects.
• Active: The number of objects currently in use (e.g., running containers, images used by running containers).
• Size: The total disk space consumed by the objects.
• Reclaimable: The amount of disk space that can be freed by removing unused objects.

To get a more detailed view, you can use the -v flag for verbose output.

docker system df -v

This will provide a more detailed breakdown, including a list of individual images, containers, and volumes and their respective sizes.

Understanding Docker's disk usage is crucial for maintaining a healthy Docker environment and preventing your disk from filling up. You can use the information from docker system df to decide when to clean up unused images, containers, or volumes.

Summary

In this lab, you learned how to use the docker container ls command (also known as docker ps) to list Docker containers. You started by listing only running containers using docker ps and then learned how to show all containers, including stopped ones, by adding the -a flag.

Furthermore, you explored how to filter the container list based on criteria such as status and name using the --filter option. You also learned how to customize the output format to display specific information using the --format flag and how to view the disk usage of containers with the docker system df command.