Difference in docker restart policy between on-failure and unless-stopped?

Question

I have read the docker documentation about restart policy of containers. However, I failed to understand the difference between on-failure and unless-stopped.

When will I use one over the other? In which situations will a certain policy lead to starting a container and the other policy not?

Answer 1

on-failure will issue a restart if the exit code indicated a failure, whereas unless-stopped behaves like always and will keep an instance running unless the container is stopped.

You can try with the hello-world to see the difference.

docker run --restart on-failure hello-world will run once and exit successfully, and running a subsequent docker ps will indicate no currently running instances of the container.

However, docker run --restart unless-stopped hello-world will restart the container even if it successfully exits, so subsequently running docker ps will show you a restarting instance until you stop the container.

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                                  PORTS               NAMES
4d498ebd13a6        hello-world         "/hello"            2 seconds ago       Restarting (0) Less than a second ago                       modest_keldysh