Restart policies in Docker - Commands & Configuration

Introduction

When a container crashes or the host machine reboots, Docker does not restart it by default. Restart policies tell Docker what to do automatically — whether to always restart, restart only on failure, or never restart.

When you run a web server that must stay running even if it crashes unexpectedly.

When you want containers to start automatically after a host server reboot.

When you run background workers and want them restarted only if they exit with an error.

When you run one-time task containers and want to make sure they never restart after completing.

When you deploy long-running services in production that must self-heal without manual intervention.

Commands

Runs an nginx container that always restarts automatically — whether it crashes, exits cleanly, or the Docker daemon restarts.

Terminal

docker run -d --restart always nginx

Expected Output

b2c3d4e5f6a7890bcdef1234567890abcdef1234567890abcdef1234567890ab

→

--restart always - Restarts the container under any exit condition including Docker daemon restart

Runs a worker container that restarts only if it exits with a non-zero error code, up to a maximum of 3 attempts.

Terminal

docker run -d --restart on-failure:3 my-worker

Expected Output

c3d4e5f6a7b8901cdef1234567890abcdef1234567890abcdef1234567890abc

→

--restart on-failure:3 - Restarts on error exit only, max 3 retries before giving up

Inspects the restart policy of the running nginx container to confirm it is set correctly.

Terminal

docker inspect --format='{{.HostConfig.RestartPolicy.Name}}' nginx

Expected Output

always

Updates the restart policy of an already running container without restarting it. 'unless-stopped' restarts automatically except when manually stopped.

Terminal

docker update --restart unless-stopped nginx

Expected Output

nginx

→

--restart unless-stopped - Restart automatically unless the container was explicitly stopped by the user

Key Concept

If you remember nothing else from this pattern, remember: use --restart always for services that must never go down, and --restart on-failure for workers where a clean exit means the job is done.

Common Mistakes

Using --restart always for batch jobs or one-time tasks

The container restarts forever even after successfully completing its work, wasting resources.

Use --restart on-failure for jobs that should only retry on errors, or no restart policy for one-time tasks.

Forgetting that 'always' restarts even after a manual docker stop

After restarting Docker daemon, containers with 'always' come back even if you stopped them intentionally.

Use --restart unless-stopped so manually stopped containers stay stopped after a daemon restart.

Not setting any restart policy for production services

The container stays down after a crash until someone manually restarts it, causing downtime.

Always set --restart unless-stopped or --restart always for production services.

Summary

Use --restart always to keep a container running under any exit condition including daemon restarts.

Use --restart on-failure:N to retry only on error exits up to N times — good for workers.

Use --restart unless-stopped to auto-restart except when you explicitly stop the container.