Docker List Containers Example
This example will show you how to list containers with Docker, one of the most popular software of the moment. Apart from just listing the containers, we will see the useful options that this command is provided with.
For this example, Linux Mint 18 and Docker version 1.12.1 have been used.
You may skip Docker installation and jump directly to the beginning of the example below.
1. Installation
Note: Docker requires a 64-bit system with a kernel version equal or higher to 3.10.
We can install Docker simply via apt-get
, without the need of adding any repository, just installing the docker.io
package:
sudo apt-get update sudo apt-get install docker.io
For more details, you can follow the Install Docker on Ubuntu Tutorial.
2. Setting up some containers
2.1. Pulling a sample image
As you should know, before creating containers, we need Docker images.
The easiest way to obtain a Docker image is to pull one from the Docker Hub. You don’t have to have an account for pulling images.
Let’s pull a Busybox image:
docker pull busybox
2.2. Creating sample containers
Let’s create several containers:
docker run busybox docker run busybox echo "Hello world" docker run --name=mybusybox busybox docker run -it busybox
Note: after the last container execution, open a new terminal, since the have set the interactive mode for it.
3. Listing containers
The Docker command for listing containers is ps
(yes, not a very good name). So, let’s try it:
docker ps
For which will return an output like the following:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e723bc39fdd9 busybox "sh" 3 minutes ago Up 3 minutes jolly_bhabha
The first thing that probably will come to our minds is that we are just seeing a single container, when we actually instantiated several of them. This is because ps
command just shows the active, running containers. And, actually, we only have a single container running: the one we instantiated interactively.
If we want to show all the containers, we have to pass the -a
(--all
) option to ps
:
docker ps -a
In this case, the output would be:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e723bc39fdd9 busybox "sh" 3 minutes ago Up 3 minutes jolly_bhabha 642aec18d638 busybox "sh" 3 minutes ago Exited (0) 3 minutes ago mybusybox fe574b4fcca5 busybox "sh" 3 minutes ago Exited (0) 3 minutes ago grave_ramanujan 0583be5c5598 busybox "echo 'Hello world'" 3 minutes ago Exited (0) 3 minutes ago pedantic_hoover e4ceead785b3 busybox "sh" 3 minutes ago Exited (0) 3 minutes ago cranky_murdock
3.1. Formatting the output
You may find the ps
output not very pretty, since the lines can be wrapped if the width of the terminal window is not big enough. Fortunately, this command allows custom formatting. This is achieved with the --format
option. The format is specified in “Go Template”, which is pretty easy:
docker ps --format '{{.<column-name1>}}[ {{.<column-nameN>}} ]'
Specifying as many columns as we want. Of course, the formatting is compatible with -a
option.
For example, if we would just want to see the names, we could execute:
docker ps -a --format '{{ .Names }} {{ .Status }}'
Which would show:
jolly_bhabha Exited (0) 5 minutes ago mybusybox Exited (0) 5 minutes ago grave_ramanujan Exited (0) 5 minutes ago pedantic_hoover Exited (0) 5 minutes ago cranky_murdock Exited (0) 5 minutes ago
The name of the fields are case sensitive, and for same cases the field name we have to use with --format
is not very intuitive. So this is the list of the field name we have to use for each column:
CONTAINER ID
:ID
IMAGE
:Image
COMMAND
:Command
CREATED
:RunningFor
STATUS
:Status
PORTS
:Ports
NAMES
:Names
Note that the fields which were named CONTAINER ID
and CREATED
, use completely different names for the formatting. If we want to show the header for each column, we can add the table
identifier before we specify the format, for example:
docker ps -a --format 'table {{ .ID }} {{ .Names }}'
Which would make the output look like:
CONTAINER ID NAMES e723bc39fdd9 jolly_bhabha 642aec18d638 mybusybox fe574b4fcca5 grave_ramanujan 0583be5c5598 pedantic_hoover e4ceead785b3 cranky_murdock
And, to align each column, we can use the tabulation \t
character between each one:
docker ps -a --format 'table {{ .ID }}\t{{ .Names }}'
Having a nicer formatting:
CONTAINER ID NAMES e723bc39fdd9 jolly_bhabha 642aec18d638 mybusybox fe574b4fcca5 grave_ramanujan 0583be5c5598 pedantic_hoover e4ceead785b3 cranky_murdock
3.2. Saving format templates in Docker configuration file
We have seen how useful can be the custom formatting for container outputting. But, on the other hand, it requires to write quite a lot, which perhaps make thing that it’s not worth.
Fortunately, Docker allows to define a default formatting configuration for the ps
command, so, every time we execute it, it will show the output as defined, without the need of specifying the --format
option.
For this, we just have to open the config.json
file with our favorite editor, located in the .docker/
folder, in the home directory:
vim ~/.docker/config.json
And add a --table
value for the psFormat
entry, e.g.:
{ "psFormat": "table {{ .ID }}\t{{ .Names }}\t{{ .Status }}" }
Now, just executing the following Docker command:
docker ps -a
The output would be:
CONTAINER ID NAMES STATUS e723bc39fdd9 jolly_bhabha Exited (0) 10 minutes ago 642aec18d638 mybusybox Exited (0) 10 minutes ago fe574b4fcca5 grave_ramanujan Exited (0) 10 minutes ago 0583be5c5598 pedantic_hoover Exited (0) 10 minutes ago e4ceead785b3 cranky_murdock Exited (0) 10 minutes ago
3.3. Using filters
The remaining interesting feature for container listing is the filtering of the results. This is useful if we are dealing with several containers, and we just want information about some of them.
For filtering the output, the option -f
(--format
) is used. The format is the following:
docker ps -f "key1=value1" -f "key2=value2" -f "keyN=valueN"
As you can see, we can specify as many filters as we want, but, for each of them, we have to specify the filter option.
For example, we could filter by the container name:
docker ps -a -f "name=mybusybox"
Showing the following output:
CONTAINER ID NAMES STATUS 642aec18d638 mybusybox Exited (0) 15 minutes ago
(Keeping the configuration as we saw in previous section).
The filter also supports regular expressions, for example:
docker ps -a -f "name=/*_"
Looking for container names with an underscore, outputting:
CONTAINER ID NAMES STATUS e723bc39fdd9 jolly_bhabha Exited (0) 15 minutes ago fe574b4fcca5 grave_ramanujan Exited (0) 15 minutes ago 0583be5c5598 pedantic_hoover Exited (0) 15 minutes ago e4ceead785b3 cranky_murdock Exited (0) 15 minutes ago
4. Summary
In this tutorial, we have seen how to list containers created with Docker. But we have gone further than that: we have seen the options that the command for listing containers provide, to make the output prettier and more suitable for our needs, seeing also how to save the configuration to use it as default.