Docker Engine supports four container restart policies — `no`, `on-failure`, `always` and `unless-stopped`. What does each one mean, and how do you set or change the policy on a container?

## What a restart policy is A Docker container wraps one main process (PID 1 inside the container). When that process exits, the container enters the `exited` state and, by default, simply stays there. A **restart policy** is a per-container instruction to the Docker daemon (`dockerd`): *when this container's main process exits, should you start it again?* It is the daemon's built-in supervision, comparable to what `systemd`'s `Restart=` does for a host service. The policy is stored in the container's configuration (`HostConfig.RestartPolicy`), so it survives daemon restarts and host reboots, and you can read it back with `docker inspect`. ## The four policies **`no`** — the default. Nothing is restarted automatically. Use it for one-shot jobs, batch tasks, and anything supervised from outside (a systemd unit, an orchestrator, a CI runner). **`on-failure[:max-retries]`** — restart *only* if the container exited with a non-zero status. Exit code 0 means "the job finished", so the container is left stopped. The optional `:N` caps the number of consecutive restart attempts; without it, retries are unlimited. This is the right policy for batch work that should be retried but must be allowed to succeed and stay finished. **`always`** — restart the container every time it stops, regardless of exit code, and start it again whenever the daemon starts. The subtlety: if you run `docker stop`, the daemon records that the stop was deliberate and does not immediately restart it — but that memory does not survive a daemon restart, so after a `dockerd` restart or host reboot the container comes back up. **`unless-stopped`** — identical to `always` except for that last point: a container you explicitly stopped remains stopped even after the daemon restarts. This is usually the policy people actually want for long-running services on a single host, because "I took it down on purpose" survives a reboot. ## Setting and changing it At creation time: `docker run -d --restart=unless-stopped nginx`. In Compose, the `restart:` key on a service takes the same four values (`restart: on-failure:3`). On an existing container, `docker update --restart=<policy> <container>` changes the policy in place without recreating it — useful when you started something with the default `no` and want it supervised. Two constraints worth remembering: `--restart` is mutually exclusive with `--rm` (Docker refuses the combination, since auto-removal and auto-restart contradict each other), and in Swarm mode a *service*'s restart behaviour comes from the service spec (`deploy.restart_policy`, with conditions `none` / `on-failure` / `any`), not from this container-level flag. ## What counts as "stopped" The distinction that trips people up is *deliberate* versus *unexpected*. `docker stop` (and `docker kill`) is deliberate: even with `always`, the daemon will not immediately bring the container back. A process that dies on its own — crash, OOM kill, a bad config, a clean `exit 0` — is unexpected, and the policy applies. Note that `on-failure` keys purely off the exit status, so a container killed by a signal (e.g. exit 137 from SIGKILL, 143 from SIGTERM) counts as a failure and will be retried. ## Guard rails the daemon applies The policy only takes effect once the container has *started successfully* — the daemon requires it to stay up briefly before it treats it as a running container worth supervising, so a container that cannot start at all doesn't spin forever at full speed. Between attempts the daemon waits an exponentially increasing delay (starting around 100 ms and doubling), so a crash-looping container costs the host far less than a tight loop would. `docker inspect -f '{{.RestartCount}}' <id>` shows how many times the daemon has restarted it. ## Choosing one Rules of thumb: long-running service on a plain Docker host → `unless-stopped`. Retryable batch job → `on-failure:N`. Anything under an external supervisor or orchestrator → `no`, so exactly one component owns restarts. `always` is mostly a legacy default; prefer `unless-stopped` unless you genuinely want the container to come back after a reboot even though an operator had taken it down. Finally, a restart policy reacts only to *process exit*. A container whose process is alive but wedged — deadlocked, not serving traffic — will never be restarted by Docker, no matter which policy you chose; a failing `HEALTHCHECK` marks a plain container `unhealthy` but does not restart it.