DevOps

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.
 
 
 
 
 
 

Tip
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.

Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Inline Feedbacks
View all comments
Back to top button