How to set a container restart policy in Docker

A restart policy tells Docker whether a container should stay stopped, restart after a failure, or come back after the Docker daemon starts again. Changing the policy on an existing container lets an operator tighten recovery behavior without recreating the workload first.

Docker supports four restart-policy values for containers: no, on-failure[:max-retries], always, and unless-stopped. The right choice depends on whether the container is a long-running service, a one-shot job, or a workload that should retry only after a non-zero exit.

The restart policy does not take effect until the container has been running for at least 10 seconds, and a manual stop suppresses automatic restarts until the container is started again or the Docker daemon restarts. When the container is managed by Docker Compose or Swarm, the service definition should be updated as well so the next recreate does not replace the manual setting.

1. Check the current restart policy on the target container.

   $ docker inspect --format '{{json .HostConfig.RestartPolicy}}' web-app
   {"Name":"no","MaximumRetryCount":0}

   Name shows the active policy, and MaximumRetryCount stays at 0 unless on-failure:N is used.

2. Apply the required restart policy with docker update.

   $ docker update --restart unless-stopped web-app
   web-app

   Use unless-stopped for a long-running container that should return after crashes and host reboots but stay down after an explicit stop.

   If the container comes from Docker Compose or a Swarm service, update the restart setting in the project or service definition too or the next recreate can replace this change.

3. Confirm that Docker stored the new policy on the container.

   $ docker inspect --format '{{json .HostConfig.RestartPolicy}}' web-app
   {"Name":"unless-stopped","MaximumRetryCount":0}

   Use on-failure:3 to retry only non-zero exits up to three times, or use always when the container should restart again after the Docker daemon itself restarts.