Docker Restart Policy — Automatic Container Recovery
What Is a Docker Restart Policy in Simple Terms?
When a container stops — either because it crashed, its process exited, or you stopped it manually — what should Docker do? Restart it immediately? Wait and retry? Leave it stopped? The restart policy answers this question.
The Four Restart Policies
Bash
no (default): Container stops -> stays stopped forever Requires manual docker start to bring it back Good for: one-off jobs, development testing on-failure: Container exits with non-zero code -> restart Container exits with code 0 -> stays stopped Good for: application services (crash = restart, intentional exit = respect it) always: Any exit -> restart (even exit code 0) Survives Docker daemon restart (starts on boot) docker stop -> restarts anyway! Good for: critical services that should never be down unless-stopped: Like always, but respects manual docker stop Crash -> restart Daemon restart -> restart (starts on boot) docker stop -> stays stopped until manually started Good for: most production servicesUsing Restart Policies
Bash
# Production service — restarts on crash, respects manual stopdocker run -d \ --name payment-api \ --restart unless-stopped \ registry.razorpay.in/payment-api:v3.1.0 # Critical service — must always be runningdocker run -d \ --name nginx \ --restart always \ nginx:1.25 # Application service — restart only on crashesdocker run -d \ --name worker \ --restart on-failure:5 \ worker-image:latest# :5 = give up after 5 consecutive failures# Prevents infinite restart loop on a broken container # One-off job — no restartdocker run \ --restart no \ --rm \ migrate-image:latest # In Docker Composeservices: api: restart: unless-stopped postgres: restart: unless-stopped migration: restart: no # run once and doneChecking Restart Count
Bash
# See how many times a container has restarteddocker inspect payment-api \ --format '{{.RestartCount}}'# 0 = healthy, never restarted# 5 = restarted 5 times — investigate why# 47 = restart loop — application is broken, fix it # See restart policy in effectdocker inspect payment-api \ --format '{{.HostConfig.RestartPolicy.Name}}'# unless-stoppedRestart Policy vs Kubernetes
TEXT
Docker restart policy = Kubernetes restartPolicy Docker no = Kubernetes Never Docker on-failure = Kubernetes OnFailure Docker always = Kubernetes Always But in Kubernetes, the Deployment controller also handlesnode failures — if a node goes down, pods are rescheduledto other nodes. Docker restart policy only handlesprocess-level crashes on the same host.COMMON MISTAKE / WARNING**Common Mistake:** Using `--restart always` for a container with a bug that makes it crash immediately on start. Docker will restart it thousands of times per hour, generating enormous amounts of log output and consuming CPU. Always investigate the restart count — if it is above 5, fix the bug instead of letting Docker keep restarting it.