How to use docker container prune command to remove stopped containers

Introduction

In this lab, you will learn how to effectively manage your Docker environment by removing stopped containers using the docker container prune command. We will begin by creating and stopping several containers to simulate a real-world scenario. Then, you will explore different ways to prune these stopped containers, including removing all of them, removing those created before a specific time, and selectively removing containers based on labels. This hands-on experience will equip you with the skills to keep your Docker system clean and optimized.

Skills Graph

Create and stop some containers

In this step, we will learn how to create and stop Docker containers. Docker containers are lightweight, portable, and self-sufficient units that contain everything needed to run an application.

First, let's pull a Docker image that we will use to create containers. We will use the ubuntu image, which is a minimal Ubuntu operating system.

docker pull ubuntu

You should see output indicating that the image is being downloaded.

Using default tag: latest
latest: Pulling from library/ubuntu
...
Status: Downloaded newer image for ubuntu:latest
docker.io/library/ubuntu:latest

Now that we have the image, let's create and run a container from it. We will use the docker run command. The -d flag runs the container in detached mode (in the background), and the --name flag assigns a name to the container.

docker run -d --name my-ubuntu-container ubuntu sleep infinity

This command creates a container named my-ubuntu-container from the ubuntu image and runs the sleep infinity command inside it. The sleep infinity command keeps the container running indefinitely.

You should see a long string of characters as output, which is the container ID.

<container_id>

To verify that the container is running, we can use the docker ps command.

docker ps

This command lists all running containers. You should see your my-ubuntu-container listed.

CONTAINER ID   IMAGE          COMMAND            CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X seconds ago   Up X seconds             my-ubuntu-container

Now, let's create another container, but this time we won't give it a specific name. Docker will automatically generate a name for it.

docker run -d ubuntu sleep infinity

Again, you will see the container ID as output.

<container_id>

Run docker ps again to see both running containers.

docker ps

You should now see two containers listed.

CONTAINER ID   IMAGE          COMMAND            CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X seconds ago   Up X seconds             my-ubuntu-container
<container_id>   ubuntu         "sleep infinity"   X seconds ago   Up X seconds             <random_name>

Now, let's stop the container named my-ubuntu-container. We can use the docker stop command followed by the container name or ID.

docker stop my-ubuntu-container

You should see the container name as output, indicating that it has been stopped.

my-ubuntu-container

Run docker ps again. You will see that my-ubuntu-container is no longer listed, as docker ps only shows running containers.

docker ps

To see all containers, including stopped ones, use the docker ps -a command.

docker ps -a

You should now see both containers, with my-ubuntu-container having a status of Exited.

CONTAINER ID   IMAGE          COMMAND            CREATED         STATUS                      PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X minutes ago   Exited (0) X seconds ago              my-ubuntu-container
<container_id>   ubuntu         "sleep infinity"   X minutes ago   Up X minutes                          <random_name>

Finally, let's stop the second container using its container ID. You can get the ID from the output of docker ps -a. Replace <container_id> with the actual ID of the second container.

docker stop <container_id>

You should see the container ID as output.

<container_id>

Run docker ps -a one last time to confirm that both containers are stopped.

docker ps -a

Both containers should now have a status of Exited.

CONTAINER ID   IMAGE          COMMAND            CREATED         STATUS                      PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X minutes ago   Exited (0) X seconds ago              my-ubuntu-container
<container_id>   ubuntu         "sleep infinity"   X minutes ago   Exited (0) X seconds ago              <random_name>

Prune all stopped containers

In the previous step, we created and stopped two containers. Stopped containers still consume disk space and resources. In this step, we will learn how to remove all stopped containers using the docker container prune command.

First, let's list all containers, including stopped ones, to see the containers we will be removing.

docker ps -a

You should see the two containers we stopped in the previous step.

CONTAINER ID   IMAGE          COMMAND            CREATED         STATUS                      PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X minutes ago   Exited (0) X minutes ago              my-ubuntu-container
<container_id>   ubuntu         "sleep infinity"   X minutes ago   Exited (0) X minutes ago              <random_name>

Now, let's prune all stopped containers. The docker container prune command removes all stopped containers.

docker container prune

Docker will ask for confirmation before removing the containers. Type y and press Enter to proceed.

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y

You should see output indicating the containers that were removed and the total reclaimed space.

Deleted Containers:
<container_id>
<container_id>

Total reclaimed space: XMB

To verify that the stopped containers have been removed, list all containers again.

docker ps -a

This time, you should see no output, indicating that there are no containers (running or stopped) left.

CONTAINER ID   IMAGE          COMMAND            CREATED         STATUS         PORTS     NAMES

Prune stopped containers created before a specific time

In the previous step, we learned how to prune all stopped containers. Sometimes, you might want to remove only stopped containers that were created before a certain time. This can be useful for cleaning up old containers while keeping newer ones. In this step, we will learn how to prune stopped containers created before a specific time using the --filter flag with the until filter.

First, let's create a few containers and stop them so we have something to prune.

docker run -d --name container-old-1 ubuntu sleep infinity
docker run -d --name container-old-2 ubuntu sleep infinity

Wait a few seconds, then create another container. This will be our "newer" container.

sleep 5
docker run -d --name container-new-1 ubuntu sleep infinity

Now, stop all the containers.

docker stop container-old-1 container-old-2 container-new-1

List all containers to see their status and creation time.

docker ps -a --format "{{.Names}}\t{{.Status}}\t{{.CreatedAt}}"

You should see output similar to this, with different creation times:

container-old-1	Exited (0) X seconds ago	YYYY-MM-DD HH:MM:SS +0000 UTC
container-old-2	Exited (0) X seconds ago	YYYY-MM-DD HH:MM:SS +0000 UTC
container-new-1	Exited (0) X seconds ago	YYYY-MM-DD HH:MM:SS +0000 UTC

Now, let's prune the stopped containers that were created before a specific time. We will use the until filter with the docker container prune command. The until filter takes a timestamp or a duration. For this example, we will use a duration, specifying that we want to remove containers created more than 10 seconds ago.

docker container prune --filter "until=10s"

Docker will ask for confirmation. Type y and press Enter.

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y

You should see output indicating that the older containers were removed. The newer container should not be listed as deleted.

Deleted Containers:
<container_id_old_1>
<container_id_old_2>

Total reclaimed space: XMB

To verify that only the older containers were removed, list all containers again.

docker ps -a --format "{{.Names}}\t{{.Status}}"

You should only see the container-new-1 listed with an Exited status.

container-new-1	Exited (0) X seconds ago

Prune stopped containers with a specific label

In the previous steps, we learned how to prune all stopped containers and stopped containers based on their creation time. In this step, we will explore another useful way to filter containers for pruning: using labels. Labels are key-value pairs that you can attach to Docker objects, including containers, to organize and manage them.

First, let's create a few containers with different labels.

docker run -d --name container-label-app --label app=frontend ubuntu sleep infinity
docker run -d --name container-label-env --label env=development ubuntu sleep infinity
docker run -d --name container-no-label ubuntu sleep infinity

Now, stop all the containers.

docker stop container-label-app container-label-env container-no-label

List all containers and their labels to see the labels we've applied.

docker ps -a --format "{{.Names}}\t{{.Labels}}"

You should see output similar to this:

container-label-app	app=frontend
container-label-env	env=development
container-no-label

Now, let's prune only the stopped containers that have the label app=frontend. We will use the --filter flag with the label filter.

docker container prune --filter "label=app=frontend"

Docker will ask for confirmation. Type y and press Enter.

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y

You should see output indicating that the container with the app=frontend label was removed.

Deleted Containers:
<container_id_app_frontend>

Total reclaimed space: XMB

To verify that only the container with the app=frontend label was removed, list all containers again.

docker ps -a --format "{{.Names}}\t{{.Labels}}"

You should now see only the containers with the env=development label and no label.

container-label-env	env=development
container-no-label

You can also prune containers that do not have a specific label by using the ! prefix with the label filter. Let's prune the container that does not have the label env=development.

docker container prune --filter "label!=env=development"

Confirm the removal by typing y and pressing Enter.

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y

You should see output indicating that the container without the env=development label was removed.

Deleted Containers:
<container_id_no_label>

Total reclaimed space: XMB

List all containers one last time to confirm that only the container with the env=development label remains.

docker ps -a --format "{{.Names}}\t{{.Labels}}"

You should only see the container-label-env listed.

container-label-env	env=development

Summary

In this lab, we learned how to create and stop Docker containers using the docker run and docker stop commands, and how to list running containers with docker ps. We then explored the docker container prune command to efficiently remove stopped containers. Specifically, we practiced pruning all stopped containers, removing stopped containers created before a specific time using the --filter until option, and selectively removing stopped containers based on labels using the --filter label option. These steps demonstrated practical methods for managing and cleaning up stopped containers in a Docker environment.