Docker Compose — Restart Policies

1 minute read

Restart policies determine what happens when a container crashes or the host reboots.

Available Policies

Policy Behavior
no Never restart (default)
always Always restart
on-failure Restart on non-zero exit code
unless-stopped Restart unless manually stopped

Configuration

services:
  api:
    image: myapi:latest
    restart: unless-stopped

  db:
    image: postgres:16
    restart: unless-stopped

  worker:
    image: myworker:latest
    restart: on-failure

Policy Comparison

Container exits with code 0:
  no             → stays stopped
  always         → restarts ✓
  on-failure     → stays stopped
  unless-stopped → restarts ✓

Container exits with code 1 (error):
  no             → stays stopped
  always         → restarts ✓
  on-failure     → restarts ✓
  unless-stopped → restarts ✓

After docker compose stop:
  no             → stays stopped
  always         → stays stopped (until daemon restart)
  on-failure     → stays stopped
  unless-stopped → stays stopped ✓

After host reboot:
  no             → stays stopped
  always         → restarts ✓
  on-failure     → stays stopped
  unless-stopped → restarts ✓ (if was running before stop)
Service Type Policy Reason
Web server unless-stopped Should always run
Database unless-stopped Should always run
Queue worker on-failure Restart on crash, not on success
One-time task no Run once and done
Init/migration no or on-failure Complete and exit

With on-failure Retry Limit

You can limit restart attempts with the deploy key (Compose v2):

services:
  worker:
    image: myworker:latest
    deploy:
      restart_policy:
        condition: on-failure
        max_attempts: 5
        delay: 10s
        window: 60s

Verify Restart Count

docker inspect myapp-api-1 --format '{{.RestartCount}}'

Summary

Policy Crash Clean Exit Manual Stop Reboot
no No No No No
always Yes Yes No Yes
on-failure Yes No No No
unless-stopped Yes Yes No Yes*

*If running before stop.

Quick Reference

Item Detail
no Never restart (default)
always Always restart, even on success
on-failure Restart only on non-zero exit
unless-stopped Restart unless manually stopped
Production Use unless-stopped for long-running services

You may also enjoy