How to Stop and Terminate a Docker Container

This article covers seven key points about stopping and terminating Docker containers. We'll cover the pause and stop commands, how to stop and shutdown completely, how to force a stop and shutdown, how to mass delete halted containers, the signal and timeout options, and how to resolve `permission denied'.

1. Stop Docker Container Command

The basic form of the command to stop or terminate a running Docker container is as follows.

docker container stop [OPTIONS] CONTAINER [CONTAINER...].

Because Docker containers are Unix process-based, this command gives them time to stop running by sending a SIGTERM signal to the corresponding Docker container. . It then kills that process by sending a SIGKILL signal.

The SIGTERM signal tells the process that we will wait for it to safely exit before killing it. SIGKILL is the equivalent of a forced shutdown in other operating systems.

Let's look at the stop command again, where CONTAINER is the name or ID of the container you want to stop. This command allows you to stop one or more containers at once.

In [OPTIONS] you can add any options you want, such as the --time option. The options we will use most often will be covered in the following sections.

A container stopped with the stop command can be restarted with the start command. The command is shown below, and you can add options such as -a, -i, and others that we saw in the Running Docker Containers post.

$ docker container start [OPTIONS] CONTAINER [CONTAINER...].

Let's look at a simple example of shutting down and restarting a running `nginx' container.

First, (1) we look at the name or ID of this container, and with that, (2) we execute the stop command. Note that (3) a stopped container will not be looked up in the ls query without the --all option. Then (4) restart it with the start command, and (5) verify.

$ docker container ls # (1)
container id image command
6f3e40d12122 nginx "/docker-entrypoint...."
 
$ docker container stop 6f3e # (2)
6f3e
 
$ docker container ls # (3)
 
$ docker container start 6f3e # (4)
6f3e
 
$ docker container ls # (5)
container id image command
6f3e40d12122 nginx "/docker-entrypoint...."

2. Pause Docker Container Command

Sometimes you may need to pause a running container. This is typically done when system resources are limited and resources are running low. When you pause a Docker container, you temporarily give back the resources that were allocated to it.

The command to pause a container is the following command:

$ docker container pause [OPTIONS] CONTAINER [CONTAINER...]

This is similar to the stop command we saw in Section 1. When you run the above command, the Docker daemon sends a `SIGSTOP' signal to the corresponding container, temporarily stopping its processes.

To resume the paused container, issue the following command

$ docker container unpause CONTAINER [CONTAINER...]

This command sends a SIGCONT signal to the paused Docker container, causing it to resume its work.

Here's an example

$ docker container ls # check container ID
container id image ... status
6f3e40d12122 nginx ... Up 11 seconds
 
$ docker container pause 6f32 # Pause the container
6f3e
 
$ docker container ls # Verify container pause
container id image ... status
6f3e40d12122 nginx ... Up 26 seconds (Paused)
 
$ docker container unpause 6f3e # Restart the container
6f3e
 
$ docker container ls # Confirm container redo
6f3eCONTAINER ID IMAGE ... STATUS
6f3e40d12122 nginx ... Up 44 seconds

Containers in the Paused state are queried with the docker container ls command, The STATUS entry will say (Paused). If you run the unpause command in this state, you will see it running again.

3. Stopping and Killing All Docker Containers

Docker doesn't provide a separate option to stop and kill all containers in bulk. However, you can stop all your containers by using two docker commands together like this

$ docker container stop $(docker container ls -aq)

The -a option in the docker container ls command we used here is the --all option, which asks for containers in all states, The -q option is the --quiet option, which only prints container IDs.

This list of IDs is then passed as an argument to the stop command using the shell script syntax $().

In practice this looks like

$ docker container ls -aq # check target container IDs
6f3e40d12122
7d392cc25008
 
$ docker container stop $(docker container ls -aq) # Stop the entire container
6f3e40d12122
7d392cc25008
 
$ docker container ls # Confirm full container stop
container id image command

This is an easy way to stop all containers, but it can unexpectedly stop containers that shouldn't be running. So use it with care.

4. Remove command after stopping a container

When Docker reorganized its command structure, it removed the ability to kill and delete a container at the same time. Therefore, it is best to use the following two commands back to back.

$ docker container stop [container-id]
$ docker container rm [container-id]

The `docker container rm' command is used to remove a stopped Docker container, For more information, see the container removal post.

However, if you really want to do this with just one command, you can use the You can use the --force option of the docker rm command, which is Docker's legacy command.

$ docker rm -f [container-id]

This command will immediately send a SIGKILL signal to that container, forcing it to shut down. Remember that deleting a container also deletes all data inside that container, so always do it carefully and thoughtfully.

5. Using the kill command and the --signal option to force a container to shut down

When stopping and terminating a container, the docker container stop command is always the first choice, as it safely kills all processes. However, when a container is in an unresponsive state, or has been created with an incorrect image and is difficult to manipulate, a forced shutdown is necessary.

Docker provides a separate command to kill a container. This is the kill command.

$ docker container kill [OPTIONS] CONTAINER [CONTAINER...]

This command sends a SIGKILL signal to one or more containers, killing them immediately.

If you want to send a signal other than SIGKILL, you can specify it with the --signal option. However, in the case of kill, the process already ignores other signals, so I don't think it's reasonable to expect a different response.

If you use the kill command, you may be forced to shut down immediately, resulting in unexpected data loss, etc. Therefore, you should back up or prepare for this.

6. Setting a Container Stop Timeout

In Section 1, I mentioned that when you run the docker container stop command, it waits for the container to send a SIGTERM'signal to safely stop the process. The default value for this time that docker waits is set to 10 seconds.

While 10 seconds isn't a lot of time, if the process of shutting down a container is complicated enough to take more than 10 seconds, Docker will forcibly kill it with a SIGKILL signal. This can lead to unexpected data loss, etc. Therefore, you should sometimes be able to give it more time.

The --time option of the stop command does just that.

$ docker container stop -t 30 my_container

If you ran a command like the one above, your container should have 30 seconds to complete the shutdown process, after which it will be forced to shut down.

7. What to do if permission denied occurs

You may encounter the permission denied error message while shutting down a container. As the message says, this happens because the current user does not have sufficient permissions to manipulate the Docker container.

Docker requires root or administrator privileges by default. If you're a home user, you're free to set your permissions, but if you're working in an enterprise environment or collaborating, there's a chance that your permissions aren't set as high as they should be.

This can be solved by running docker commands as root, or by joining the docker group, which allows non-host users to use docker.

7.1. Using the sudo keyword

Using the root privilege is easy. Use the sudo keyword together as follows. You'll need to know the password for your host account.

$ sudo docker container stop [container-id]

7.2. Adding to the docker user group

Here's a way to grant docker permissions to the current user without having to use the sudo keyword in every command. Run the command below, log out and log in as the current user, and the group settings will be applied.

$ sudo usermod -aG docker $USER

The above command adds the currently logged in user ($USER) to the group named docker (-aG: append Group), (usermod: modify user) to change user properties. This method also requires a password for the sudo command.

These are two ways to get Docker permissions and fix the permission denied problem.

8. Final thoughts

In this post, we've covered how to stop, pause, kill, stop and delete a Docker container, force kill, set a timeout, and troubleshoot permission issues, and troubleshooting permission issues. Hopefully this will help you in your actual development process.