How to Stop Docker Containers

Introduction

The lifetime of a Docker container depends on how long its default command runs. Once the command stops running, Docker automatically stops the container.

Some containers, such as those running web servers, are designed to run indefinitely. When users decide they no longer need such containers, they must stop them manually. The same applies to containers in an error state.

This tutorial will show you how to stop Docker containers.

Prerequisites

• Command-line access.
• Administrative privileges on the system.
• Docker installed.

Stop Docker Container Gracefully (docker stop)

The recommended way to stop Docker containers is to use the docker stop command, which provides time (ten seconds by default) for the container to gracefully terminate its processes before quitting. The grace period avoids potential problems related to the abrupt termination of containers.

The syntax for the docker stop command is:

docker stop [option] [container-name-or-id]

For example, to stop a container named test-stop, enter the following:

docker stop test-stop

If successful, the command echoes back the name of the stopped container.

To stop a container with the ID 7a4cfbea094b, type the command below:

docker stop 7a4cfbea094b

docker stop Options

docker stop features two options that can be appended as arguments to the main command:

• The -s (--signal) option allows sending a custom system call signal to the container. The flag accepts the signal's name (e.g., SIGINT) or a number corresponding to its place in the syscall table.
• The -t (--time) enables the user to customize the duration of the grace period before Docker kills the container. The option accepts values in seconds.

Force Stop Docker Container (docker kill)

When the container is in an error state, it may become unresponsive and refuse to stop. The docker kill command provides a way to force quit a misbehaving container.

Below is the syntax of the docker kill command:

docker kill [option] [container-name-or-id]

For example, type the following command to force quit the container named test-kill:

docker kill test-kill

The output echoes back the name of the container.

docker kill Options

The docker kill command accepts only the -s (--signal) option as a command argument. As in the case of docker stop, this option allows the user to pass a system call signal to the container.

docker stop vs. docker kill

Both docker stop and docker kill can terminate a running container. However, they differ in how they handle the exiting process:

• The docker stop command sends the SIGTERM signal (or another stop signal, such as SIGQUIT, defined in the image metadata) and waits for the container to stop gracefully. If the container does not quit on its own during the specified grace period, the command sends the SIGKILL signal and forcefully terminates the container.
• The docker kill command immediately sends a SIGKILL signal to the container and interrupts the execution of its processes.

Always use docker stop to ensure that there are no errors when the container starts the next time. Use docker kill for unresponsive containers only.

Conclusion

This tutorial presented two commands to stop Docker containers, docker stop and docker kill. While docker stop gracefully shuts down container processes, docker kill can force quit a misbehaving container.

Containers are often stopped because they need to be replaced with an updated version. Read our article to learn how to update the Docker image and container.