What is Docker Restart Policy? | DevOps Dictionary

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 services

Using Restart Policies

Bash

# Production service — restarts on crash, respects manual stop
docker run -d \
  --name payment-api \
  --restart unless-stopped \
  registry.razorpay.in/payment-api:v3.1.0
 
# Critical service — must always be running
docker run -d \
  --name nginx \
  --restart always \
  nginx:1.25
 
# Application service — restart only on crashes
docker 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 restart
docker run \
  --restart no \
  --rm \
  migrate-image:latest
 
# In Docker Compose
services:
  api:
    restart: unless-stopped
  postgres:
    restart: unless-stopped
  migration:
    restart: no    # run once and done

Checking Restart Count

Bash

# See how many times a container has restarted
docker 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 effect
docker inspect payment-api \
  --format '{{.HostConfig.RestartPolicy.Name}}'
# unless-stopped

Restart 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 handles
node failures — if a node goes down, pods are rescheduled
to other nodes. Docker restart policy only handles
process-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.