Docker Restart Policies Explained: no, on-failure, always, unless-stopped

Docker restart policies are defined rules that dictate how a container should behave when it crashes, when the Docker daemon restarts, or when the host machine reboots. They are foundational mechanisms used in DevOps, production environments, and microservice architectures to ensure automatic recovery, maintain application availability, and minimize manual intervention.

1. Why Do We Need Restart Policies? (The Production Problem)

In a production environment, containerized applications face unexpected challenges such as application bugs, server reboots, and daemon crashes.

• The Status Quo Challenge: If you run a standard container (such as an Ubuntu container or a web server) and your machine or Docker daemon restarts, the container enters an Exited state. Without a restart policy, it stays down permanently until an engineer manually intervenes.
• Production Stability: Production workloads require high availability and minimal downtime. Restart policies bridge the gap between unexpected application failures and continuous uptime by automating container recovery.
• Cross-Platform Knowledge: Understanding Docker restart policies provides a direct mental model for container orchestration platforms like Kubernetes, where similar restart and pod-resurrection concepts are heavily utilized.

2. Core Mental Model & Configuration Rules

Restart policies act as automated watchdogs configured at container startup.

Configuration Mechanism

Restart policies are specified using the --restart flag when starting a container:

docker run -d --restart=<policy-name> nginx

Note: You can only apply or modify restart policies on a container during its initial run time creation. If a container is already running or created without the flag, you cannot apply a restart policy to it on the fly.

3. The Four Docker Restart Policy Categories

Docker provides four distinct restart policy options to handle various application lifecycles and operational requirements.

4. Deep Dive: Policy 1 — no (Default Policy)

When you run a container without specifying a restart policy, Docker applies the default no policy.

• Behavior:
  • The container will not restart automatically under any circumstance when it exits normally, crashes, the Docker daemon restarts, or the host system reboots.
  • If the container exits, it remains permanently in the stopped state until an operator manually steps in (docker start <container_id>).
• Use Cases:
  • Ideal for local testing environments, debugging sessions, temporary container executions, and short-lived build or test tasks.
• Production Warning: This policy is not recommended for production environments because it guarantees downtime when infrastructure hiccups occur.

5. Deep Dive: Policy 2 — always

The always policy instructs Docker to attempt to restart the container in every scenario, regardless of how it stopped or why it failed.

• Behavior:
  • Docker restarts the container when it crashes, exits with an error, the Docker daemon restarts, or the system reboots.
  • Even if an administrator manually stops the container during runtime, Docker may still spin it back up once the Docker daemon restarts or the host machine reboots.
• Use Cases:
  • Best for critical production services that must remain up and running continuously (e.g., core web servers, public-facing API endpoints, backend microservices, and databases).

6. Deep Dive: Policy 3 — unless-stopped

The unless-stopped policy is very similar to always, with one crucial operational distinction designed to respect administrative intent.

• Behavior:
  • Docker restarts the container when it crashes, the Docker daemon restarts, and the system reboots.
  • The Exception: If an administrator or engineer explicitly stops the container manually during runtime, Docker respects that decision and will not automatically restart it—even across daemon restarts or system reboots—until it is manually started again.
• Use Cases:
  • Highly favored by DevOps engineers for general production services, long-running web applications, and internal microservices where automatic recovery is required unless maintenance is explicitly being performed.

7. Deep Dive: Policy 4 — on-failure and Retry Limits

The on-failure policy is engineered specifically for tasks that are expected to complete successfully, restricting restarts exclusively to abnormal failures.

• Behavior:
  • Docker restarts the container only if it exits with a non-zero exit code (indicating an application error or crash).
  • If a container exits with a 0 exit code (meaning normal, successful completion), Docker leaves it in the stopped state.
  • It will not restart if the container is manually stopped, or when the daemon/host restarts unless a failure state preceded it.
• Retry Limits:
  • You can restrict how many times Docker attempts to restart a failing container by appending a retry limit colon:
    BASH

    Copy

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

  • In this example, if the application crashes repeatedly, Docker will attempt recovery up to 3 times before giving up.
• Use Cases:
  • Ideal for batch jobs, worker containers, data processing pipelines, CI/CD runner tasks, and background process services that need automated retries upon crashing without looping infinitely on persistent code bugs.

8. Best Practices for Production Environments

When architecting containerized systems, apply these core guidelines when choosing restart policies:

• Avoid Default Policies in Production: Never leave production workloads on the default no policy, as unexpected reboots will cause permanent service outages.
• Default to unless-stopped for General Services: Use unless-stopped for most standard applications because it provides automated recovery while respecting manual administrative shutdowns during maintenance windows.
• Use always for Absolute Core Infrastructure: Reserve always for core infrastructural services that must never be allowed to stay down under any unmanaged circumstance.
• Use on-failure with Limits for Jobs: Apply on-failure alongside a retry limit (e.g., :3 or :5) for background tasks, data processors, and cron-like jobs to prevent endless crash-loops while granting automated recovery for transient network or resource glitches.

Summary and Key Takeaways

• Definition: Docker restart policies dictate container recovery behavior following crashes, daemon restarts, and host reboots.
• Core Purpose: They automate recovery, eliminate manual intervention, and guarantee high availability in production environments.
• Configuration Rule: The policy must be declared at container creation time via the --restart flag during docker run.
• The no Policy: The default setting; does not restart containers automatically. Reserved for debugging and testing.
• The always Policy: Restarts containers universally across crashes, reboots, and daemon restarts regardless of manual intervention.
• The unless-stopped Policy: Similar to always, but respects manual administrative stops by keeping the container down until manually restarted.
• The on-failure Policy: Restarts containers only when they exit with a non-zero error code, supporting optional retry limits.
• Kubernetes Parallel: Mastering restart policies in Docker builds a direct conceptual foundation for managing pod restart policies in Kubernetes.