How to List Docker Containers

How do you list all the docker containers present on your system?

There are two ways to do that:

• Using docker ps command (older and popular method)
• Using docker container command (newer and less known method)

Let me quickly list the commands with the most common examples for your quick reference.

ps command	container command	Command displays
docker ps	docker container ls	running containers
docker ps -a	docker container ls -a	all containers
docker ps -f "status=exited"	docker container ls -f "status=exited"	stopped containers
docker ps -q	docker container ls -q	ID of running containers
docker ps -l	docker container ls -l	latest created container

As you can see, both commands are identical with their options.

However, since docker wants to organize commands properly, they recommend using the docker container ls command.

For this reason, I'll be using docker container ls command in the detailed examples even though the docker ps command is more popular and widely used.

Show running docker containers

Without any options, you'll see only the running containers.

docker container ls

The output is a detailed one:

abhishek@handbook:~$ docker container ls
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
f03e48cb07ea        ubuntu              "bash"              8 seconds ago       Up 6 seconds                            ubuntu-c-1
93f84eb0f579        alpine              "/bin/sh"           23 seconds ago      Up 22 seconds                           alp_con2

If this is your first time seeing this output, let me explain the different elements of the output:

• Container ID - Unique numeric ID to identify a container
• Image - Docker image that created the container
• Command - The default command that is executed while starting a container
• Created - Relative time when the container was created
• Status - The state of the container (will be explained later)
• Ports - Published ports of the container
• Name - Name of the container. If none provided, a random name is assigned anyway.

List all docker containers

If you want to see all the containers on your system, use the option -a.

docker container ls -a

Here's a sample output and you can see that now it shows several stopped containers as well.

abhishek@handbook:~$ docker container ls -a
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
f03e48cb07ea        ubuntu              "bash"              37 minutes ago      Up 37 minutes                                ubuntu-c-1
93f84eb0f579        alpine              "/bin/sh"           37 minutes ago      Up 37 minutes                                alp_con2
1c1c04a84186        alpine              "bash"              38 minutes ago      Created                                      alp_con
6fbc4bf4897b        ubuntu              "/bin/bash"         2 hours ago         Exited (0) 2 hours ago                       fervent_hofstadter
8b9565ba7661        alpine              "/bin/sh"           2 hours ago         Exited (0) 2 hours ago                       beautiful_williamson
853e748608bc        hello-world         "/hello"            2 hours ago         Exited (0) 2 hours ago                       stoic_engelbart

Display only stopped containers

If you want to list only the stopped containers, you can filter the output on exited status.

docker container ls --filter "status=exited"

Here's the filtered output:

abhishek@handbook:~$ docker container ls --filter "status=exited"
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
6fbc4bf4897b        ubuntu              "/bin/bash"         2 hours ago         Exited (0) 2 hours ago                       fervent_hofstadter
8b9565ba7661        alpine              "/bin/sh"           2 hours ago         Exited (0) 2 hours ago                       beautiful_williamson
853e748608bc        hello-world         "/hello"            2 hours ago         Exited (0) 2 hours ago                       stoic_engelbart

The exited state is for stopped containers. There are a few more status for the containers that you can use for different purposes:

• created - A container that has been created but not started
• restarting - A container in the process of being restarted
• running - A running container
• paused - A container whose processes have been paused
• exited - A stopped container
• dead - A container that was tried to be stopped but failed

In fact, the filtering is not limited to status, you can filter based on other elements of the container listing output like container id, name or image. The next example uses this concept.

Show containers associated with an image

You can use filters to display all the containers associated with a certain image only using the ancestor filter.

docker container ls -a --filter "ancestor=image_name"

Here's an output that displays all the containers associated with the docker image of Alpine Linux.

abhishek@handbook:~$ docker container ls -a --filter "ancestor=alpine"
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
93f84eb0f579        alpine              "/bin/sh"           48 minutes ago      Up 48 minutes                                alp_con2
1c1c04a84186        alpine              "bash"              49 minutes ago      Created                                      alp_con
8b9565ba7661        alpine              "/bin/sh"           2 hours ago         Exited (0) 2 hours ago                       beautiful_williamson

Display only container id

Did you notice that all the above commands have detailed output on the containers?

If you don't need the additional information like container name, associated image, its status, you can use the quiet option -q.

For example, if I use the -q option in the previous example, it gives me only the IDs of all containers associated with Alpine Linux.

abhishek@handbook:~$ docker container ls -a -q --filter "ancestor=alpine"
93f84eb0f579
1c1c04a84186
8b9565ba7661

This comes handy in situations like removing all the containers of a docker image.

Well, that's enough for this docker tutorial. I think I have mentioned enough usescases for listing containers in docker. Stay subscribed for more such tutorials.