How to List Docker Containers

Docker

How to List Docker Containers

March 1, 2023

This guide is part of the "Snippets" series. This series is focused on providing simple and accessible tutorials on various topics relating to development!

One of the essential tasks when working with Docker containers is listing them. Docker provides several commands to list containers, both running and stopped, and filter and format the output.

In this article, we will explore the various Docker commands that are used to list containers, their use cases, best practices, and limitations.

Let's start with the most important thing, the actual commands.

Docker Command	Description
`docker ps`	Lists all the running Docker containers.
`docker ps -a`	Lists all the Docker containers, both running and stopped.
`docker ps -q`	Lists only the IDs of running Docker containers.
`docker container ls`	A shorter version of `docker ps`.
`docker container ls -a`	A shorter version of `docker ps -a`.
`docker container ls -q`	A shorter version of `docker ps -q`.
`docker container ls --filter`	Allows you to filter Docker containers based on various criteria.
`docker container ls --format`	Allows you to specify the output format of the listed Docker containers.
`docker inspect`	Shows detailed information about a specific Docker container.
`docker stats`	Shows real-time usage statistics of all the running Docker containers.

These commands are essential for managing Docker containers, and you can use them in various use cases, such as monitoring and troubleshooting Docker containers, identifying container ID or names, or filtering the containers based on specific criteria.

Listing Running Containers

The docker container ls command is used to list the running Docker containers. It is a shorter version of the docker ps command and provides a concise output that includes information about the container ID, image, command, status, and creation time. You can also use various flags and options with this command to filter and format the output.

Here's an example output of the docker container ls command:

The output shows the following information about the running Docker containers:

CONTAINER ID: The unique identifier for the container.
IMAGE: The name of the Docker image used to create the container.
COMMAND: The command that is executed when the container is started.
CREATED: The date and time when the container was created.
STATUS: The current status of the container.
PORTS: The ports that are exposed by the container.
NAMES: The name of the container.

In the example output, we can see that there are two running Docker containers, an Nginx web server and a MySQL database server. We can see their container IDs, the images they are based on, the commands used to start them, the status, and the ports they are using.

Listing All Containers

To list all the Docker containers on a system, you can use the docker ps -a command. This command lists all the containers, both running and stopped. Here's an example output:

The output shows information about all the Docker containers, both running and stopped, and includes the same information as the docker container ls command, such as container ID, image, command, creation time, status, ports, and names.

Listing Latest Containers

If you want to list only the latest created Docker containers, you can use the docker ps -n command. This command lists the most recently created n number of Docker containers, where n is the number of containers you want to list.

For example, if you want to list the 5 most recently created Docker containers, you can use the following command:

docker ps -n 5

Here's an example output:

Listing the latest created Docker containers is useful for tasks such as monitoring newly created containers, identifying recently started containers, or troubleshooting newly created containers. It allows you to quickly get an overview of the most recent containers and focus on troubleshooting or monitoring them.

How to Disable Truncation

By default, the output of the docker container ls command is truncated to fit the width of the terminal window. This truncation can make it difficult to read the output, especially if you have long container names or command lines.

To disable truncation and see the full output, you can use the docker container ls --no-trunc command. This command displays the full container ID, image, and command lines, without truncating them.

Here's an example output of the docker container ls --no-trunc command:

As you can see from the output, the container ID, image, and command lines are not truncated and are displayed in full. This makes it easier to read the output and identify the containers' details.

Disabling truncation is useful when you have long container names, commands, or arguments that are truncated by default. However, keep in mind that disabling truncation may result in output that is too wide for the terminal window, which may make it difficult to read or analyze the output.

Listing the ID Only (Quiet Mode)

The docker container ls command provides a lot of information about the Docker containers, which can be overwhelming if you only need to retrieve specific information, such as container IDs, for use in a script or automation tool.

To retrieve only the container IDs of the running containers, you can use the docker container ls -q command. This command lists only the container IDs of the running containers, without any additional information or formatting.

Here's an example output of the docker container ls -q command:

65f07f352a8a
ee03fbc8e1d8
b8e4d6844d67

The output shows only the container IDs of the running Docker containers, without any additional information or formatting. This output is useful when you need to retrieve only the container IDs, such as for use in a script or automation tool.

You can also use the docker ps -q command to achieve the same result. This command is a shorter version of docker container ls -q and lists only the container IDs of the running containers.

Another useful flag that you can use with the docker container ls command is the -q flag in combination with the -a flag to list only the container IDs of all the containers, including the stopped ones. This can be achieved by running the following command:

docker container ls -aq

This command lists only the container IDs of all the Docker containers, both running and stopped, without any additional information or formatting.

Quiet mode is useful when you only need to retrieve specific information, such as container IDs, without any additional information or formatting. It helps to simplify the output and make it easier to parse and use in scripts or automation tools.

Viewing Container Size

To view the size of a Docker container, you can use the docker ps command in combination with the --size flag. This flag adds a SIZE column to the output, which shows the size of each running container's writable layer in bytes.

Here's an example of the docker ps --size command output:

As you can see from the output, the SIZE column shows the size of each container's writable layer in bytes, along with a virtual size in parentheses. The virtual size is the sum of the size of the writable layer and the size of the read-only image layers.

The container size can be useful for identifying containers that are taking up too much disk space, especially if you're working with a limited disk space or trying to optimize the use of resources. You can use this information to identify the containers that are taking up the most disk space and take appropriate actions, such as removing the containers or optimizing their size by removing unnecessary files or layers.

Customizing the Output

The docker container ls command provides a lot of information about the Docker containers, but sometimes you may need to customize the output to fit your specific use case. For example, you may only need to retrieve specific information, such as the container name, image name, and IP address, to use in a script or automation tool.

To customize the output of the docker container ls command, you can use the --format flag. This flag allows you to specify a Go template that defines the output format of the command.

Here's an example of the docker container ls --format command with a customized output:

docker container ls --format '{{.Names}} {{.Image}} {{.Networks.IPAMConfig.IPv4Address}}'

This command lists only the container name, image name, and IP address of the running containers, without any additional information or formatting.

Here's an example output of the above command:

webserver nginx 172.19.0.2/16
mysql-db mysql 172.19.0.3/16

The output shows the container name, image name, and IP address of each running container, separated by a space.

You can customize the output using any Go template that defines the output format of the command. The available template variables are listed in the table below.

Variable	Description
`.ID`	The container ID.
`.Image`	The image name.
`.Command`	The command that was used to start the container.
`.CreatedAt`	The time the container was created.
`.RunningFor`	The duration that the container has been running.
`.Ports`	The ports that are exposed by the container.
`.Status`	The status of the container.
`.Size`	The size of the container.
`.Names`	The container name.
`.Networks`	The container's network settings.
`.Mounts`	The container's mount settings.

You can use any combination of these variables to create a custom output format for the docker container ls command. For example, you can use the following Go template to list only the container ID, image name, and running status:

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

This command would list only the container ID, image name, and running status of the containers, separated by a space.

d41c0bcb27d6 nginx:latest Up 5 minutes
a3cdca1f93e9 mysql:latest Up 1 hour

Customizing the output of the docker container ls command using template variables is useful when you only need to retrieve specific information, such as container names, image names, or running status, for use in a script or automation tool. It helps to simplify the output and make it easier to parse and use in scripts or automation tools.

Using Advanced Filters

The docker container ls command provides various flags and options that allow you to filter and sort the output based on various criteria, such as container status, names, labels, and more. However, sometimes you may need more advanced filtering options, such as filtering based on container metadata or using regular expressions to match patterns in the output.

To perform advanced filtering of the output of the docker container ls command, you can use the --filter flag in combination with key-value pairs that specify the filter criteria.

Here's an example of the docker container ls --filter command with advanced filtering:

docker container ls --filter "label=com.example.version=1.0"

This command lists only the containers that have a label com.example.version with a value of 1.0.

You can also use multiple filters at once, separated by commas:

docker container ls --filter "label=com.example.version=1.0" --filter "status=running"

This command lists only the running containers that have a label com.example.version with a value of 1.0.

You can use various filter keys to filter the output, such as ancestor, before, since, exited, health, id, isolation, name, status, label, and more. The full list of filter keys is available in the Docker documentation.

Advanced filtering is useful when you need to retrieve specific containers based on complex criteria, such as metadata or patterns in the output. It allows you to filter the output based on various filter keys and values and retrieve only the relevant containers that match the filter criteria.

Conclusion

Listing Docker containers is a crucial task when working with Docker, and there are various commands and tools available to achieve this. By default, Docker provides a docker container ls command that lists the running containers and provides details such as container ID, image name, command, and status.

Apart from the default command, there are other commands available for listing Docker containers. One option is to use the docker ps command, which provides a similar output to the docker container ls command. This command can be used with various flags and options to customize the output, such as listing all containers, showing the latest containers, and disabling truncation.

Another way to list Docker containers is by using third-party tools such as Portainer and Docker Compose. Portainer provides a web-based interface for managing Docker containers and allows you to view the list of containers, inspect their details, and perform various management tasks. Docker Compose is a tool for defining and running multi-container Docker applications, and it provides various commands for listing and managing the containers defined in a Docker Compose file.

In addition to the default commands and third-party tools, you can also use various APIs and SDKs to list Docker containers programmatically. For example, the Docker Engine API provides a /containers/json endpoint that lists all the running containers, and you can use various SDKs, such as the Docker SDK for Python, to interact with this endpoint and retrieve container details.

In conclusion, there are various commands, tools, and APIs available for listing Docker containers, and the choice depends on your specific use case and requirements.