Docker - what does `docker run --restart always` actually do?

Restart policies

Using the --restart flag on Docker run you can specify a restart policy for how a container should or should not be restarted on exit.

When a restart policy is active on a container, it will be shown as either Up or Restarting in docker ps. It can also be useful to use docker events to see the restart policy in effect.

docker run --always 

Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container.

I recommend you this documentation about restart-policies

Documentation - Restart policies

Update Docker v19.03

Restart policies (--restart)

Use Docker’s --restart to specify a container’s restart policy. A restart policy > controls whether the Docker daemon restarts a container after exit. Docker supports the following restart policies:

always Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container.

$ docker run --restart=always redis

Documentation - Restart policies

To configure the restart policy for a container, use the --restart flag when using the docker run command. The value of the --restart flag can be any of the following:

no Do not automatically restart the container. (the default)

on-failure Restart the container if it exits due to an error, which manifests as a non-zero exit code.

always Always restart the container if it stops. If it is manually stopped, it is restarted only when Docker daemon restarts or the container itself is manually restarted.

unless-stopped Similar to always, except that when the container is stopped (manually or otherwise), it is not restarted even after Docker daemon restarts.

The following example starts a Redis container and configures it to always restart unless it is explicitly stopped or Docker is restarted.

$ docker run -d --restart unless-stopped redis

This command changes the restart policy for an already running container named redis.

$ docker update --restart unless-stopped redis

And this command will ensure all currently running containers will be restarted unless stopped.

$ docker update --restart unless-stopped $(docker ps -q)

Restart policy details

Keep the following in mind when using restart policies:

• A restart policy only takes effect after a container starts successfully. In this case, starting successfully means that the container is up for at least 10 seconds and Docker has started monitoring it. This prevents a container which does not start at all from going into a restart loop.
• If you manually stop a container, its restart policy is ignored until the Docker daemon restarts or the container is manually restarted. This is another attempt to prevent a restart loop.
• Restart policies only apply to containers. Restart policies for swarm services are configured differently.

Documentation