How to List Only the Stopped Containers in Docker

1. Pull Nginx Image From the Docker Hub
2. List the Docker Images
3. Run Containers From the Nginx Image
4. List the Running Containers
5. Stop a Running Container
6. List the Stopped Container Using the docker ps Command
7. List the Stopped Container Using the docker container ls Command
8. Conclusion

Docker provides us with useful commands that we can use to manage our images and containers, but some of the commands are not obvious. For example, we can use the Docker command docker ps to show a list of running containers or the docker command docker ps -a to display a list of all containers, whether stopped or running.

One functionality that is not obvious is showing a list of only the stopped containers. In this tutorial, we will learn how to display a list of only the stopped containers in Docker.

Pull Nginx Image From the Docker Hub

In this tutorial, we will use the Nginx image to run containers from it and use these containers to achieve the objective of this article.

Open a new terminal window using the keyboard shortcut ALT+F12 on your computer, then use the following command to pull an Nginx image from the docker hub.

~$ docker pull nginx

Since we have not specified the tag, this command will pull the latest version of Nginx. We can view the download details on the terminal window, as shown below.

Using default tag: latest
latest: Pulling from library/nginx
e9995326b091: Pull complete
71689475aec2: Pull complete
f88a23025338: Pull complete
0df440342e26: Pull complete
eef26ceb3309: Pull complete
8e3ed6a9e43a: Pull complete
Digest: sha256:943c25b4b66b332184d5ba6bb18234273551593016c0e0ae906bab111548239f
Status: Downloaded newer image for nginx:latest
docker.io/library/nginx:latest

List the Docker Images

Once the download has been completed, we can verify that the Nginx image was downloaded using the following command that lists all the images.

~$ docker image ls

If other images had been installed before, they would all be listed using this command. In our case, we have just displayed the image used in this tutorial to verify that the image was downloaded.

The image details are shown below:

REPOSITORY                        TAG       IMAGE ID       CREATED       SIZE
nginx                             latest    76c69feac34e   2 days ago    142MB

Run Containers From the Nginx Image

For testing purposes, we will only run two containers with the name container-one and container-two, respectively. On the same terminal window, execute the following commands sequentially to run the two containers using the nginx image.

Running container-one:

~$ docker run --name container-one -d -p 3000:80 nginx

Output:

9e70a29947c373df2abd4748271d252f297c6a06669f7cffb04fe95ee5fca671

Running container-two:

~$ docker run --name container-two -d -p 5000:80 nginx

Output:

43cd017b94062e47c6c3f868ed74fb5ca7920522e870eceb58115e388e9d43a5

Note that the first container exposes port 3000 on the host to listen on port 80 on the container while the second container exposes port 5000 on the host to listen on the same port as the previous container.

List the Running Containers

In the previous section, we have run two containers with the name container-one and container-two. To verify whether these containers are running, we can use the following command, which lists all running containers.

~$ docker ps

Output:

CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS                  NAMES
43cd017b9406   nginx     "/docker-entrypoint.…"   4 minutes ago    Up 4 minutes    0.0.0.0:5000->80/tcp   container-two
9e70a29947c3   nginx     "/docker-entrypoint.…"   24 minutes ago   Up 24 minutes   0.0.0.0:3000->80/tcp   container-one

Stop a Running Container

Before listing the stopped container, we must stop a container, and we can use the following command to stop a container using its name. Be free to run and stop multiple containers.

~$ docker stop container-one

Output:

container-one

When we execute the docker ps command, we will find that only container-two is running. In the next section, we will learn how to list only the stopped container, which is the main objective of this tutorial.

List the Stopped Container Using the docker ps Command

The docker ps command has a --filter flag that we can specify to filter the containers based on a condition. The value of the --filter flag expects a condition that will be used to provide an output.

On the same terminal window, use the following command to filter containers with the status of exited.

~$ docker ps --filter "status=exited"

Output:

CONTAINER ID   IMAGE                   COMMAND                  CREATED          STATUS                      PORTS                    NAMES
9e70a29947c3   nginx                   "/docker-entrypoint.…"   48 minutes ago   Exited (0) 18 minutes ago                            container-one

List the Stopped Container Using the docker container ls Command

This command has the same syntax as the previous example. The docker container ls command has a --filter flag that we can specify to filter the containers based on a condition. Since the --filter flag is the same, we only need to provide the condition to filter the containers with the status of exited, as shown below.

~$ docker container ls --filter "status=exited"

Output:

CONTAINER ID   IMAGE                   COMMAND                  CREATED          STATUS                      PORTS                    NAMES
9e70a29947c3   nginx                   "/docker-entrypoint.…"   48 minutes ago   Exited (0) 18 minutes ago                            container-one

Note that the --filter flag should be provided in the form of key-value pairs, and in case there are multiple filters, ensure that multiple flags are provided.

In this tutorial, we have used the filter named status to filter the containers based on status. However, the docker documentation provides other strategies we can leverage to filter the containers.

Conclusion

In this tutorial, we have learned how to list only the stopped containers in Docker by leveraging an Nginx container. The two approaches covered to do this include listing a stopped container using the ps command and listing a stopped container using the container ls command.

The two commands have a --filter flag that accepts a key-value pair to filter the containers based on a specific condition.