Restart policies — no, always, unless-stopped, on-failure · Docker & Containers

A restart policy tells the daemon what to do when a container’s main process exits. That is its entire scope, and holding on to it resolves most of the confusion in this area — including the one the previous lesson ended on.

An unhealthy container has not exited. It is running, its PID 1 is alive, and it is still bound to its published port. The restart policy is therefore not consulted, will never be consulted, and adding restart: always changes nothing about it. Restart policies and health status are two independent mechanisms that never speak to each other.

What restart policies do cover is worth knowing exactly, because three of their behaviours are surprising.

The four policies

Policy	Process exits non-zero	Process exits zero	Daemon restarts (container running)	Daemon restarts (container manually stopped)
`no`	stays exited	stays exited	stays exited	stays exited
`on-failure[:N]`	restarts, up to `N` if given	stays exited	stays exited	stays exited
`always`	restarts	restarts	starts	starts
`unless-stopped`	restarts	restarts	starts	stays stopped

Two cells in that table are the whole story.

on-failure does not survive a daemon restart. The documentation is explicit: the policy “only prompts a restart if the container exits with a failure. It doesn’t restart the container if the daemon restarts.” A batch worker with on-failure that was running happily when you upgraded Docker is simply not running afterwards, and nothing logs an error about it. This is the most commonly missed row in the table.

always and unless-stopped differ in exactly one cell. Both restart on any exit. Both come back on daemon restart if they were running. The only difference is what happens to a container you stopped on purpose when the daemon later restarts: always brings it back, unless-stopped leaves it alone.

The container you stopped for maintenance came back on its own

You stop a container deliberately — to take a backup, to swap a config file, to keep it out of the way during a migration. Hours later, unattended package updates restart the Docker daemon. The container is running again, in the middle of your maintenance, with the old configuration, writing to the volume you were copying.

The policy was always, and always means what it says: on daemon startup the container is started regardless of its current state. Your manual stop was a state, not an instruction the daemon remembered.

unless-stopped exists precisely for this. It records that the stop was deliberate and honours it across daemon restarts and host reboots. For anything you might ever stop by hand — which is everything — unless-stopped is the correct default, and always should be a considered choice rather than a habit.

The related surprise, in the other direction: a manual stop suspends the restart policy entirely until the daemon restarts or you start the container yourself. So a container you stopped will not be restarted by its policy no matter how many times something else tries to kill it. That is deliberate — it is what prevents a restart loop while you are working on something.

The ten-second rule

“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.”

A container that fails in under ten seconds on its very first run is not considered to have started, so the policy does not engage. This prevents a container with a typo in its command from spinning uselessly forever.

It also produces a genuinely confusing symptom the first time you meet it: a container with restart: always that exits immediately and then does not restart. Nothing is broken. The daemon has decided it never started in the first place. The evidence is in the container’s state, not in the policy.

The backoff

Once the policy does engage, the daemon does not restart in a tight loop. It backs off, and the exact behaviour is worth knowing because it is what a restart loop looks like from the outside.

What the restart manager actually does

The daemon’s restart manager holds a per-container timeout with three rules:

The first restart waits 100 ms.
Each subsequent restart doubles the wait — 100 ms, 200 ms, 400 ms, 800 ms, and so on.
The wait is capped at 1 minute. After roughly ten failures the container is being restarted once a minute and stays there.
If the container ran for more than 10 seconds, the timeout resets to 100 ms, regardless of how it then exited.

Two consequences follow directly, and they matter more than the numbers.

There is no attempt limit for always and unless-stopped. They retry forever, once a minute, until something changes. The idea that “Docker gives up after five attempts” is not correct for these policies. Only on-failure:N has a cap, and only when you supply the N — a bare on-failure also retries without limit.

The ten-second reset is what distinguishes a crash loop from a slow leak. A container that dies instantly stays in backoff and settles at one restart per minute. A container that runs for a minute and then crashes resets to 100 ms every time, so it restarts immediately, over and over — which looks much healthier in docker ps and is usually the worse problem. The RestartCount is what tells them apart.

During the backoff, docker ps shows the container’s status as Restarting (1) 12 seconds ago — the number in parentheses is the exit code, not the attempt number, and that is where the diagnosis usually starts.

Diagnosing a restart loop

Read-only / Safewhat a loop looks like— The exit code in parentheses is the container's exit status.

$ docker ps -a --filter status=restarting --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'

NAMES     STATUS                          IMAGE
worker    Restarting (1) 43 seconds ago   example/worker:2.4.1
importer  Restarting (137) 8 seconds ago  example/importer:1.9.0

Illustrative output

Read-only / Safethe four facts that identify the cause— Count, exit code, uptime and the last thing it said.

CONTAINER=worker

# How many times, and when did the current attempt start?
docker inspect -f 'restarts={{.RestartCount}} started={{.State.StartedAt}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' "$CONTAINER"

# The last words before each death.
docker logs --tail 40 --timestamps "$CONTAINER"

# Watch the loop live: die and start events, with the exit code.
docker events --filter "container=$CONTAINER" --filter 'event=die' --filter 'event=start' --format '{{.Time}} {{.Status}} exitCode={{index .Actor.Attributes "exitCode"}}'

The exit code narrows it faster than the logs do:

Exit code	Almost always means
`0`	the process finished its work — with `always`/`unless-stopped` this restarts forever; the policy is wrong, not the container
`1`	application error — read the logs
`125`	the daemon rejected the `docker run` itself; a bad flag
`126`	the command was found but could not be executed; usually a missing execute bit on an entrypoint script
`127`	the command was not found in the image; usually a typo or a shell missing from a slim base
`137`	killed by `SIGKILL` — with `OOMKilled: true` it is the memory limit; without it, something sent a KILL
`139`	segmentation fault
`143`	terminated by `SIGTERM` — a clean shutdown that the policy is now undoing

137 with "OOMKilled": true is the one worth recognising instantly: that is the cgroup memory limit, and no restart policy will fix it. The container will be killed again at the same point every time, usually with the interval between kills getting shorter as caches warm faster.

Host reboot

This is the behaviour most people actually care about, and it has a precondition that has nothing to do with the policy.

Read-only / Safethe precondition— A restart policy is irrelevant if the daemon does not start.

# Is the daemon set to start at boot at all?
systemctl is-enabled docker.service
systemctl is-enabled containerd.service

# What would come back? Everything with always or unless-stopped.
docker ps -a --format '{{.Names}}\t{{.Status}}' --filter 'label=' 2>/dev/null >/dev/null
docker inspect -f '{{.Name}} {{.HostConfig.RestartPolicy.Name}} {{.State.Status}}' $(docker ps -aq) | sort -k2

On a host installed from the Docker apt or yum repositories, docker.service is enabled by default. On a host where someone installed Docker to try something and never intended it to be permanent, it may not be — and then every restart policy on the box is decoration. systemctl is-enabled docker.service is a one-line check that belongs in every post-build verification.

Given an enabled daemon, a reboot produces:

containerd and dockerd start.
Every container with always starts, whatever state it was in.
Every container with unless-stopped starts unless it was deliberately stopped.
Containers with no or on-failure stay stopped.
All of them start at roughly the same moment.

`deploy.restart_policy.delay` does not stagger container startup

Step 5 is a real problem on a host with dozens of containers — every JVM warming at once, every database doing recovery at once, every health check probing at once, on a host whose page cache is empty. The obvious-looking fix is this:

services:
  app:
    deploy:
      restart_policy:
        delay: 5s

It does not do what the name suggests. delay is “how long to wait between restart attempts” for a single container that keeps failing — it is a backoff control, not a boot stagger. It has no effect whatsoever on how many containers start simultaneously after a reboot. Nor does any flag called --restart-delay, which does not exist.

There is no Docker-level mechanism for staggering boot. The mitigations that do work are outside the restart policy:

depends_on with condition: service_healthy serialises startup along the dependency graph, so the database is healthy before the application is even started. This is the closest thing to a built-in answer.
Do not autostart at all. Set the heavy stack to no and bring it up with docker compose up -d from a systemd unit ordered after the things it needs, or by hand. On a host where a reboot is an event rather than a routine, a human decision between “the host is up” and “the host is serving” is a feature.
Fix the resource contention instead. A boot storm that overwhelms the host is usually a capacity finding, and the capacity part of this course is where it belongs.

live-restore changes what a daemon restart means

{"live-restore": true} in daemon.json keeps containers running while the daemon is stopped, rather than shutting them down with it. That makes a daemon upgrade a non-event for running workloads, and it changes the reasoning above: with live restore, restarting dockerd does not stop containers, so no restart policy is consulted and the always surprise above does not occur.

The constraints are real and worth knowing before you enable it: it supports patch (YY.MM.x) upgrades only, not major daemon upgrades; it does not work if daemon-level options such as the bridge IP or the storage driver changed; and it applies to standalone containers, not Swarm services. A daemon that is down for a long time can also fill the 64 KB log FIFO, which blocks containers from logging until the daemon is restarted.

Choosing a policy

Workload	Policy	Reasoning
Long-running production service	`unless-stopped`	comes back from every failure and every reboot, and respects a deliberate stop
Service that must never be off, even after you stopped it	`always`	the daemon overrides your stop on restart; choose this knowingly
Batch job or migration that should run once	`no`	a zero exit is success; restarting it is a bug
Job that should retry a bounded number of times	`on-failure:3`	retries on error only, gives up after three, and does not come back after a daemon restart
One-off debugging container	`no` with `--rm`	and note that `--rm` combined with `--restart` is rejected outright by the daemon
Sidecar whose lifetime should match its parent	`no`	Compose does not model this; the parent’s health check does

The default is no, which is almost never what a production container wants. The single most common production defect in this area is not choosing the wrong policy — it is not setting one at all, and finding out at the next reboot.

Configuration changeaudit and fix— Find containers with no policy, then set one. Review the list before running the second command.

# Everything with no restart policy at all.
docker inspect -f '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -q) | awk '$2=="no" || $2==""'

# Change one container without recreating it. The change is immediate
# and persists in the container's configuration.
CONTAINER=web
docker update --restart unless-stopped "$CONTAINER"

# Confirm it took.
docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' "$CONTAINER"

docker update --restart changes a running container’s policy without recreating it, which is the rare Docker operation that is both useful and free. Applying it across every container at once with docker update --restart unless-stopped $(docker ps -q) is a documented one-liner, and it is also a change to the boot behaviour of the entire host — read the list from the first command before you run the second.

In Compose, the equivalent is the restart key, and it is one of the few Compose keys that requires recreating the container to apply because it is part of the container’s host configuration:

Configuration changecompose.yaml— `restart` is the policy; `deploy.restart_policy` is the Swarm-oriented long form.

services:
web:
  image: example/web:1.4.2
  restart: unless-stopped

migrate:
  image: example/web:1.4.2
  command: ["./manage.py", "migrate"]
  restart: "no"          # runs once; a zero exit is success
  depends_on:
    db:
      condition: service_healthy

db:
  image: postgres:17
  restart: unless-stopped
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 10s
    timeout: 3s
    retries: 3
    start_period: 30s

Note restart: "no" in quotes. Unquoted, YAML parses no as the boolean false, and Compose rejects it — one of the few places the YAML 1.1 boolean rules still bite.

Verification that can fail

Service impact possibleprove the policy does what you think— Kill the process and watch. This is a real restart of a real container.

set -euo pipefail
CONTAINER=web

before=$(docker inspect -f '{{.RestartCount}}' "$CONTAINER")
echo "restarts before: $before"

# Kill PID 1 in the container. The policy should bring it back.
docker kill --signal=SIGKILL "$CONTAINER"

sleep 5
docker inspect -f 'status={{.State.Status}} restarts={{.RestartCount}} exit={{.State.ExitCode}}' "$CONTAINER"

after=$(docker inspect -f '{{.RestartCount}}' "$CONTAINER")
[ "$after" -gt "$before" ] && echo 'POLICY WORKS' || echo 'POLICY DID NOT FIRE'

If RestartCount did not increase, the possibilities are short and each is a real finding: the policy is no, the container had not been up ten seconds when you killed it, or it had been manually stopped earlier in its life and the policy is still suspended.

For the reboot case there is no substitute for rebooting. Do it once, on a new host, before it carries anything — the answer to “does this host come back on its own?” is worth more than any inspection of configuration, and it is a question that gets answered by accident at the worst possible time otherwise.

What if a container keeps restarting because its dependency is not there yet?

This is the most common restart loop on a Compose host, and it is the one where the restart policy is doing its job correctly and still producing a bad outcome.

The application starts, cannot reach the database, exits 1, and the policy restarts it. The database is still doing first-time initialisation. The application exits again. Because each attempt lasts under ten seconds, the backoff doubles — 100 ms, 200 ms, 400 ms — and by the time the database is ready the application is retrying once a minute, so the stack takes another minute to come up after everything is actually fine.

Three responses, in increasing order of how much they fix:

depends_on with condition: service_healthy. Compose does not start the application until the database’s healthcheck passes. This removes the loop at startup — and note it only governs start ordering, so it does nothing if the database fails later.
Make the application retry internally with backoff instead of exiting. A service that waits for its dependency rather than dying is strictly better behaved, and it also survives the database restarting at 03:00, which depends_on does not. The dependency-failures lesson covers the patterns.
Distinguish “not ready yet” from “misconfigured”. An application that exits 1 for both makes the loop unreadable. Exiting non-zero for a bad configuration and retrying for an unreachable dependency turns a mystery into two clear cases.

There is nothing to undo here: stop the container, fix the dependency, start it. RestartCount keeps climbing across the incident and is reset only when the container is recreated, which is worth remembering when you read it afterwards.

Knowledge check

Why this matters

A restart policy is one word that decides whether a host comes back on its own, and it is the cheapest resilience you will ever buy. Set unless-stopped on every long-running production container and most of a class of incidents disappears.

The part worth carrying beyond the syntax is what it costs. A restart policy converts a visible failure into an invisible one: the container is “up”, the dashboard is green, and RestartCount quietly reaches four thousand. It buys availability with observability, and it is a good trade only if you are watching the counter.

And it does not do the thing people most often reach for it to do. A container that is unhealthy but running has not exited, so the policy is never consulted. That gap — between “process alive” and “service working” — is the entire subject of this part of the course.

Where next

Most restart loops are not really about the container that is looping; they are about something it depends on. The next lesson is about how one failure becomes several, and the patterns that stop it.