Use Docker Stop Containers Without Screwing Things Up!

Adam Listek

Read more posts by this author.

Having trouble with Docker stop containers? Finding the correct way to stop a container is difficult with the ability to create many different containers. In this article, you will learn Docker commands to stop a container or all containers.

Read on to learn more!

Prerequisites

To follow along with this tutorial, be sure you have the following:

  • Windows 10 – The tutorial uses Windows to run Docker, but you can also apply the same general steps to Linux or macOS.
  • Docker Desktop – This tutorial uses version 3.5.2. The Docker engine is available if you’re on Linux as the GUI is not.
  • A running Docker container or containers.

Ending Containers with the docker stop Containers Command

Let’s get started with the first command: the docker stop containers command and how it accomplishes stopping containers.

For example, perhaps you need to stop a running container with the name mystifying_hofstadter and an ID of fb66ed502096. As shown in the example below, stop the container with the docker stop command.

# Stop the container via the name
docker stop mystifying_hofstadter
# Stop the container via the ID (same container)
docker stop fb66ed50209
Stopping a single Docker container via the container name or container ID.
Stopping a single Docker container via the container name or container ID.

What if you have multiple running containers, and you would like to stop those? The docker stop command supports stopping multiple container IDs, one at a time.

First, list all containers via the [docker ps](<https://docs.docker.com/engine/reference/commandline/ps/>)command and pass the container IDs to the docker stop, as shown below.

# List all running containers
docker ps
# Stop the following Docker containers via the container ID
docker stop a427a21c5558 e9dbd816f24c 31269ef5999e
Listing all running containers and then stopping them
Listing all running containers and then stopping them

What if you wish to stop all running containers without retrieving the container IDs manually and passing those to docker stop? The docker ps -q command will accomplish that. The -q parameter of docker ps command outputs only the IDs of the containers.

# Create three containers. A semi-colon separates each command
docker run -d -t ubuntu; docker run -d -t ubuntu; docker run -d -t ubuntu
# List all running containers
docker ps -q
# Retrieve all running container IDs and pass those to docker stop
docker stop $(docker ps -q)
Stopping multiple Docker containers at once.
Stopping multiple Docker containers at once.

The $(docker ps -q) construct above is a sub-expression in both Bash on Linux and PowerShell on Windows. A sub-expression instructs the shell to process one set of commands, docker ps -q, first and then return the set of results to the original command docker stop.

The docker stop command uses the SIGTERM signal. Linux signals inform a process of an event, but it is up to the process to decide how to act on a given signal.

When using the SIGTERM signal, Docker uses the signal to gracefully stop a process by waiting for a default 10 seconds before sending the SIGKILL signal, which terminates the process immediately.

Stopping a Container Using Process Signals

You learned about Docker’s default behavior (stop signal) when stopping a container. But you may not want the default behavior. Instead, you can instruct Docker to use alternative stop signals.

With the docker run command’s --stop-signal flag, you can specify the stop signal when starting the container. This flag sets the signal that will be sent to the running container when you want it to stop.

In the example below, the --stop-signal flag takes the value SIGQUIT, which tells Docker to send the SIGQUIT signal when it is time to stop the container. The example also uses the following parameters:

  • d – Runs the container in detached (background) mode. The detached mode will not allow the container to be immediately interacted with by the user since the process is running in the background.
  • t – allocates a Pseudo-TTY (PTY) console, which emulates a real terminal console in the container and stops the Ubuntu container from immediately exiting. The Ubuntu container in the example requires a PTY console to stay active in the background.
  • “image name” – What Docker image to provision the container from, in this case, the ubuntu image.
docker run -d -t --stop-signal SIGQUIT ubuntu
Specifying SIGQUIT as the signal when starting and then stopping a Docker container.
Specifying SIGQUIT as the signal when starting and then stopping a Docker container.

You can also specify the stop signal using a Dockerfile, which tells Docker how to build a container. You can add an entry to the Dockerfile specifying the stop signal with STOPSIGNAL SIGQUIT, for example. You can switch the SIGQUIT with any stop signal you would like.

Exiting Containers Immediately with docker kill

There will be times when you will want to exit containers without allowing them a grace period. The docker kill command immediately stops a container.

The example below passes the container with ID 2aa318273db5 to docker kill. The container will immediately exit via the SIGKILL signal. The container will not be allowed to a graceful exit. As a result of the command, the container will exit, and the ID of the container will be shown.

docker kill 2aa318273db5

Docker kill all containers with the command docker kill $(docker ps -q). Notice that (docker ps -q) is a sub-expression here.

Stopping and Removing a Container with docker rm

By default, when you create a container, that container is built the same as before: it is idempotent. Removing a container will have minimal impact, and with that in mind, docker rm can force-stop and remove a container. Docker issues a SIGKILL signal to the main process and removes the container from the list of available containers on your Docker installation.

If the container must keep the changed internal files or its state must be kept, then removing a container will destroy those changes. Beware of potential screw-ups!

In the following example, perhaps you have started a container that was assigned the name kind_galileo. Before removing a container, the container must be stopped, as shown below. The docker ps -a command is displaying the status of Exited for the example container.

Listing all containers, including stopped containers.
Listing all containers, including stopped containers.

Now that the container is stopped issuing the docker rm command will remove the container entirely.

docker rm kind_galileo

Instead of stopping the container to then remove the container, the combination of --force and docker rm will stop and remove the container in a single operation. The container, laughing_elion, will no longer be available to run.

docker rm --force laughing_elion

If you do not specify the --force command, you will encounter the error message Error response from daemon: You cannot remove a running container...

Stopping and removing a container.
Stopping and removing a container.

Stopping Docker Containers with Docker Compose

Docker commands are typically used on a single container, but you can create a service with multiple containers working in concert with each other. The Docker Compose tool allows you to configure a service comprised of multiple containers to work together.

As the containers within a service are designed to work together, it is best to stop the entire service itself gracefully instead of any individual container.

If you have a service running with multiple containers, [docker-compose stop] stops the service without removing the containers or the service. Follow along below to create a Docker Compose service, start the service, and ultimately stop the service gracefully.

1. Create a directory to store your configuration file. In this example, the directory C:\Articles\Ubuntu will store the file.

mkdir C:\Articles\Ubuntu

2. Next, create the file docker-compose.yml file, containing the following configuration. The below Docker Compose file creates a service with two Ubuntu containers, and when brought up, the containers do not immediately exit.

# The specification version of docker-compose
version: "3.9"
# The collection of applications composing this service
services:
  # First Ubuntu Container
  container1:
    image: ubuntu
    # Same as the -t option and allocates a Psuedo-TTY, so the container does not immediately exit.
    tty: true
  # Second Ubuntu Container
  container2:
    image: ubuntu
    tty: true

3. In a terminal session, navigate to your custom Docker configuration file directory, which in this example is C:\Articles\Ubuntu. Run the docker-compose up -d to generate and start the service created in the step before in the background as indicated by the -d option.

Starting a Docker Compose service.
Starting a Docker Compose service.

4. In the same terminal session and directory, issue the command docker-compose stop to end the service and containers gracefully.

Stopping a Docker Compose service.
Stopping a Docker Compose service.

The docker-compose command, like the docker command, also has the rm --force and kill parameters. The docker-compose parameters work on the service instead of a single container. The docker-compose kill command also takes an option -s option to specify the stop signal.

Conclusion

Docker containers are a powerful tool to create unique and segmented environments for development and production use. In this article, you have learned several ways Docker stops one or more, even all, containers. You also learned about the default stop signal Docker uses and how to change it.

With this knowledge, you now know the ins and outs of stopping Docker containers and how not to screw up when it is time to stop running containers. How do you plan to stop your containers from now on, having this newfound knowledge?

Subscribe to Stay in Touch

Never miss out on your favorite ATA posts and our latest announcements!

Looks like you're offline!