Docker Restart Policies with --restart

Automatic Container Recovery

Docker's --restart flag configures what happens when a container stops. This is essential for production deployments where services must recover automatically from crashes.

The Four Restart Policies

# Never restart (default)
docker run --restart no my-app

# Restart on non-zero exit code
docker run --restart on-failure my-app

# Restart on failure, with a maximum retry count
docker run --restart on-failure:5 my-app

# Always restart unless explicitly stopped
docker run --restart unless-stopped my-app

# Always restart, even after docker stop + daemon restart
docker run --restart always my-app

Policy Comparison

Policy	On crash	On docker stop	On daemon restart
no	No restart	N/A	No start
on-failure	Restarts	No restart	No start
on-failure:N	Restarts (up to N times)	No restart	No start
unless-stopped	Restarts	Stays stopped	Starts if was running
always	Restarts	Restarts	Always starts

Exponential Backoff

Docker uses an exponential backoff strategy for restart attempts. The first restart happens immediately, the second after 1 second, then 2, 4, 8, 16 seconds, and so on up to a maximum of 120 seconds. This prevents a crash-looping container from consuming excessive resources.

unless-stopped vs always

The key difference emerges when the Docker daemon restarts (e.g., after a server reboot):

• always: The container starts regardless of its state when the daemon stopped.
• unless-stopped: The container starts only if it was running when the daemon stopped. If you explicitly stopped it with docker stop, it stays stopped after a daemon restart.

For most production services, unless-stopped is the preferred choice because it respects manual stops.

Changing Restart Policy on a Running Container

You can update the restart policy without recreating the container:

docker update --restart unless-stopped my-container

Production Recommendations

# Web servers: always recover
docker run -d --restart unless-stopped --name web nginx

# Databases: always recover
docker run -d --restart unless-stopped --name db postgres:16

# One-off tasks: recover from transient failures
docker run --restart on-failure:3 --name migration my-migration-image

# Development: no restart (you want to see crashes)
docker run --name dev-app my-dev-image

Interaction with Orchestrators

If you use Docker Compose, Kubernetes, or Docker Swarm, the orchestrator manages restarts at a higher level. In those cases:

• Docker Compose: Use the restart key in docker-compose.yml.
• Kubernetes: Uses pod restart policies and health checks.
• Docker Swarm: Manages replicas and automatically replaces failed containers.

Setting --restart at the docker run level is still useful for standalone containers not managed by an orchestrator.