Docker Restart Policy [Explained With Examples]

Docker provides a restart policy option to let your containers restart automatically in case of certain events or failures.

This is extremely helpful in scenarios where you have to restart the Docker host (your Linux server) or if the service running in the container fails.

Docker restart policies are applied on a per-container basis. There are two ways to assign restart policy to a container. You can set it in the YAML file if you are going to use Docker Compose or Swarm or Kubernetes.

You can also set the restart policy directly in the command line when you run a container:

docker container run --restart <policy>

Let's talk about what kind of restart policy you can use.

Docker restart policies

There are following restart policies for Docker containers:

no: The default behavior is to not start containers automatically
always: Always restart a stopped container unless the container was stopped explicitly
unless-stopped: Restart the container unless the container was in stopped state before the Docker daemon was stopped (explained later)
on-failure: Restart the container if it exited with a non-zero exit code or if the docker daemon restarts

As I mentioned, if you don't explicitly add a restart policy, it goes with "no", meaning containers won't be restarted automatically.

Explaining Docker restart policies with examples

Let me show these policies in action so that you can actually visualize them. This is specially useful for understanding the difference between always and unless-stopped policies.

Always restart policy

Let's start with the always restart policy. With this policy set, the container will always be restarted unless it was stopped explicitly.

I am going to run an Alpine Linux container with always restart policy. I am naming it always-policy.

The container has one task. It runs the bash sleep command for 10 seconds and then exits.

docker container run --name always-policy --restart always alpine sleep 10

Without the always restart policy, the container would have stopped after 10 seconds. But here, it will restart automatically and run the sleep command for another 10 seconds and it continues like this.

abhishek@handbook:~$ docker ps
CONTAINER ID   IMAGE     COMMAND      CREATED          STATUS         PORTS     NAMES
1171dcfb7e06   alpine    "sleep 10"   25 seconds ago   Up 4 seconds             always-policy

You can see in the above command that though the container was created 25 seconds ago, it has been up for only 4 seconds. Please bear in mind that the same container is restarted, a new one is not created.

You can use the docker inspect command to see how many times the container has been restarted so far.

abhishek@handbook:~$ docker inspect always-policy | grep -i restartcount
        "RestartCount": 4,

If you stop the container with the stop command, it will not restart automatically afterwards. You may see in the example below that the container now has 'Exited' status instead of Up.

abhishek@handbook:~$ docker stop always-policy 
always-policy
abhishek@handbook:~$ docker ps -a
CONTAINER ID   IMAGE     COMMAND      CREATED          STATUS                     PORTS     NAMES
1171dcfb7e06   alpine    "sleep 10"   58 seconds ago   Exited (0) 6 seconds ago             always-policy

I have used the -it option for running the container with interactive terminal in the above screenshot. That was out of habit and unnecessary here.

unless-stopped vs always restart policy

The unless-stopped is similar to the always restart policy. Both restart the containers automatically and if you stop the containers explicitly, they don't restart.

But the main difference between the two is that if you stop the containers with docker stop command and then restart the docker daemon, the container with always restart policy will start the container automatically but the container with unless-stopped policy won't be restarted.

Let me show it with examples. I already have a stopped container with always restart policy. Let me create a new container named unless-stopped-policy with unless-stopped policy.

docker container run --name unless-stopped-policy --restart always alpine sleep 10

Stop the container:

docker stop unless-stopped-policy

Now I have two containers who have been explicitly stopped:

abhishek@handbook:~$ docker ps -a
CONTAINER ID   IMAGE     COMMAND      CREATED          STATUS                          PORTS     NAMES
d244b6e08899   alpine    "sleep 10"   2 minutes ago    Exited (0) About a minute ago             unless-stopped-policy
1171dcfb7e06   alpine    "sleep 10"   22 minutes ago   Exited (0) 21 minutes ago                 always-policy

Restart Docker daemon:

sudo systemctl restart docker

Now if you check the running containers, you can see that the container named always-policy is running because it was set with always restart policy.

abhishek@handbook:~$ docker ps
CONTAINER ID   IMAGE     COMMAND      CREATED          STATUS         PORTS     NAMES
1171dcfb7e06   alpine    "sleep 10"   30 minutes ago   Up 8 seconds             always-policy

The entire steps can be seen in this screenshot:

on-failure restart policy

The on-failure restart policy restarts a container if it was exited with a non-zero exit code (indicating error/failure). It also restarts the containers if the docker daemon restarts including the ones that were in the stopped state before.

If you manually stop a container with docker stop command, it exists with code zero indicating everything was normal.

Setting restart policy in Docker Compose file

By now, you have a pretty good idea about running a container with a restart policy.

If you are using something like Docker Compose for deploying containers, you can mention the restart policy for the service object in YAML file.

Here's a sample example:

version: "3.3"      
services:
    NginxProxy:
        image: "jwilder/nginx-proxy:latest"
        restart: "on-failure"
        networks: ["net"]
        ports:
            - "80:80"
            - "443:443"

Which Docker restart policy to use?

Honestly, there is no straightforward answer to this question. It depends on your use case and what you want.

I hope this article was helpful for understanding the Docker restart policy. If you have any questions or suggestions, please let me know in the comment section.