What Are Restart Policies in Docker?
A complete beginner's guide to teaching your containers how to recover on their own — so a crash at 3 a.m. doesn't mean your application stays down until someone notices.
Imagine a night security guard at an office building whose only job, if the power ever flickers and the main door lock fails, is to walk over and lock it again — automatically, without waiting for anyone to call and ask. Nobody has to be awake at 3 a.m. for that door to get secured again. Docker containers face a similar risk: they can crash, the host machine can reboot, or a process inside can simply exit unexpectedly. Without a plan, that container just stays down until a human notices and manually starts it again. A Restart Policy is Docker’s version of that automatic security guard — a rule, attached to a container, telling Docker exactly what to do the moment that container stops unexpectedly.
1The Problem Restart Policies Solve
Before learning the different policies, it helps to understand exactly what failure looks like without one.
Containers Stop for Many Reasons
A container’s life is tied directly to its main process. If that process crashes due to a bug, runs out of memory, encounters an unhandled error, or the entire host machine reboots unexpectedly, the container simply stops. By default, Docker does nothing further about it — the container sits there, stopped, exactly as it was left, until a human explicitly starts it again.
Without a restart policy, a crashed container is like a smoke alarm with a dead battery — it doesn’t fix itself, it doesn’t alert anyone automatically, and it stays silent and useless until a person happens to notice and takes action.
Why Manual Recovery Doesn’t Scale
For a single container on a personal laptop, manually restarting something after a crash is a minor inconvenience. But for real applications running unattended — web servers, databases, background workers — a container that silently stays down after a crash can mean real downtime, lost requests, and unhappy users, all because nobody happened to be watching at that exact moment.
What a Restart Policy Actually Does
In one sentence: a restart policy is a rule attached to a container at launch time that tells the Docker Engine exactly under what circumstances it should automatically start that container again after it stops — without needing a human to intervene.
2The Four Restart Policy Options
Docker offers a small, well-defined set of policies, each suited to a different kind of situation.
No
The container is never automatically restarted under any circumstances. If it stops, it simply stays stopped until someone manually starts it again. This is Docker’s behavior when no policy is specified at all.
On-Failure
The container is automatically restarted only if it exits with an error — meaning something went wrong. If it exits cleanly and intentionally, it is left stopped.
Always
The container is automatically restarted no matter why it stopped — whether it crashed, exited cleanly, or the host machine rebooted — with one notable exception described in the next chapter.
Unless-Stopped
Nearly identical to “always,” except it respects a deliberate, manual stop as a genuine instruction to stay down, rather than restarting it again on the next host reboot.
3The Critical Difference Between “Always” and “Unless-Stopped”
These two policies look almost identical on the surface, but they diverge in one specific, important scenario.
Both policies will restart a container after a crash and both will restart it after the host machine reboots. The difference only appears when a human deliberately, manually stops the container. With the “always” policy, that manual stop is essentially overridden the next time the host restarts — the container comes back regardless. With “unless-stopped,” Docker specifically remembers that a human intentionally stopped it, and respects that decision even across a host reboot, leaving it stopped until someone explicitly starts it again.
| Scenario | Always | Unless-Stopped |
|---|---|---|
| Container crashes | Restarted | Restarted |
| Host machine reboots | Restarted | Restarted (if not manually stopped before) |
| Human manually stops it, then host reboots | Restarted anyway | Stays stopped, respecting the manual stop |
“Unless-stopped” is often the more intuitive, human-friendly choice for long-running services, because it honors your explicit intent to take something down, rather than fighting against you by bringing it back regardless.
4How Docker Decides to Restart a Container
A look at the actual decision-making sequence happening behind the scenes.
flowchart TD
A[Container Stops] --> B{What restart policy is attached?}
B -- No --> C[Leave Container Stopped]
B -- On-Failure --> D{Did it exit with an error?}
D -- Yes --> E[Restart the Container]
D -- No, exited cleanly --> C
B -- Always --> E
B -- Unless-Stopped --> F{Was it stopped manually by a human?}
F -- Yes --> C
F -- No, crashed or host rebooted --> E
This decision happens automatically, entirely within the Docker Engine itself, with no need for any external monitoring tool or human observer. The restart policy is stored as part of the container’s own configuration from the moment it was created, so the Engine always knows exactly how to react whenever that particular container stops, at any point in the future.
5On-Failure and the Idea of Exit Codes
Understanding how Docker distinguishes “failed” from “finished normally.”
Every process, when it stops, reports a small number back to the operating system called an exit code. By long-standing convention, an exit code of zero means the process finished successfully and intentionally, while any non-zero exit code signals that something went wrong. The “on-failure” restart policy relies directly on this signal: it restarts the container only when that exit code indicates a genuine failure, and deliberately leaves it stopped when the exit code indicates the process simply finished its work and exited on purpose.
Think of exit codes as a short note a worker leaves before going home. “Task complete, see you tomorrow” (exit code zero) means nobody needs to be called back in. “Something broke, I had to stop” (a non-zero code) is exactly the kind of note that should trigger someone rushing back to fix it — which is what the “on-failure” policy does automatically.
This is precisely why “on-failure” is well suited to one-off jobs or batch tasks that are supposed to run once and finish — you want a crash retried, but you don’t want a successfully completed task restarted pointlessly.
6Retry Limits and Backoff Behavior
What happens when a container keeps crashing over and over, instead of recovering successfully.
A restart policy alone could, in theory, lead to an endless, rapid loop of a container crashing and immediately restarting, over and over, forever — consuming resources without ever actually fixing anything. To prevent this, the “on-failure” policy specifically supports an optional maximum retry count, letting you cap how many times Docker will attempt to restart the container before giving up and leaving it stopped.
Additionally, Docker applies an increasing delay between restart attempts — starting quickly, but growing longer with each consecutive failure. This “backoff” behavior prevents a broken container from hammering the system with rapid-fire restart attempts, giving whatever underlying problem exists (a dependency that’s temporarily unavailable, for instance) a reasonable chance to resolve itself between tries.
sequenceDiagram
participant D as Docker Engine
participant C as Container
D->>C: Start container
C-->>D: Crashes (exit code non-zero)
D->>C: Restart attempt 1 (short delay)
C-->>D: Crashes again
D->>C: Restart attempt 2 (longer delay)
C-->>D: Crashes again
D->>C: Restart attempt 3 (even longer delay)
Note over D: Maximum retries reached
D->>D: Stop retrying, leave container stopped
7Choosing the Right Policy for Different Situations
Practical guidance for matching each policy to the kind of workload it’s meant for.
Ask: Is this a long-running service or a one-off task?
Long-running services like web servers and databases generally want restart protection; short one-off jobs typically don’t need to be automatically restarted after finishing.
Ask: Should a successful, clean exit ever be restarted?
If the process is meant to run indefinitely and any exit — even a clean one — is unexpected, “always” or “unless-stopped” fits better than “on-failure.”
Ask: Do I want a manual stop to be respected permanently?
If deliberately stopping the container should mean it stays stopped even after the host reboots, “unless-stopped” is the more predictable, human-friendly choice over “always.”
Ask: Is this a batch job meant to run once?
If the container is expected to finish and exit successfully on its own, “on-failure” (or even “no”) lets it complete naturally, only stepping in if something actually breaks.
Web Servers and APIs
Typically use “unless-stopped” or “always,” since these services are meant to run continuously and any unexpected stop should be corrected automatically.
Databases
Almost always use a restart policy, since prolonged downtime of a database can cascade into failures across every dependent application.
One-Time Data Migration Scripts
Typically use “on-failure” with a limited retry count, or no policy at all, since a successful completion should never be treated as a failure to recover from.
8Advantages, Disadvantages, and Trade-offs
Restart policies are a powerful safety net, but they come with real trade-offs worth understanding.
Advantages
- Provides automatic recovery from crashes without needing a human to be watching
- Keeps critical services running across unexpected host reboots
- Requires no external tools — the capability is built directly into the Docker Engine
- Configurable retry limits prevent runaway restart loops from consuming resources
- Reduces downtime and improves the reliability of long-running applications
Disadvantages / Trade-offs
- Can mask an underlying problem by repeatedly restarting a container that’s fundamentally broken, instead of surfacing the issue clearly
- Doesn’t fix the root cause of a crash — it only reacts to the symptom
- An overly aggressive policy on a genuinely broken container can waste system resources through repeated failed restart attempts
- Choosing the wrong policy for a batch job could cause it to restart when it was never meant to run more than once
9Best Practices and Common Mistakes
Patterns that experienced teams follow when relying on restart policies in production.
Assign an explicit restart policy to every long-running container in production, rather than relying on the default “no” policy, which leaves every crash entirely unhandled.
Treating a restart policy as a substitute for real monitoring and alerting. A container silently restarting itself over and over can hide a serious, ongoing problem from a team that assumes everything is fine simply because the container “is running.”
Using “always” on a container that a team frequently needs to stop for maintenance, then being surprised when it comes back to life on the next host reboot despite being deliberately taken down.
Pair restart policies with proper logging and alerting, so that even though the container recovers automatically, someone is still notified that a crash happened at all and can investigate the underlying cause.
10Design Patterns and Anti-Patterns
Recognized right ways and wrong ways to design around automatic container recovery.
Problem
Relying entirely on an “always” restart policy as the only strategy for handling failures, with no investigation into why the container keeps crashing in the first place.
Why It’s Harmful
The container can end up in a perpetual crash-restart cycle, silently consuming resources and providing degraded or intermittent service, while the actual root cause of the instability goes completely unaddressed.
Correct Approach
Use the restart policy as a safety net alongside real monitoring, logging, and alerting, so repeated crashes are visible to a human and the underlying cause gets fixed rather than perpetually papered over.
Problem
A team wants critical services to recover automatically from crashes and host reboots, while still being able to intentionally take a container down for maintenance without it coming back unexpectedly.
Why It’s Harmful
N/A — this describes the recommended solution rather than a problem to avoid.
Correct Approach
Use “unless-stopped” for these services, giving automatic crash and reboot recovery while still respecting a deliberate, manual stop as a genuine instruction to remain down.
11Monitoring Containers That Have Restart Policies
Automatic recovery doesn’t remove the need for visibility — it changes what you should be watching for.
Since a restart policy can make a genuinely broken container look “fine” from a distance (because it’s technically running again a moment after crashing), it becomes especially important to watch the number of times a container has restarted, not just whether it’s currently up. A container that has restarted dozens of times in the last hour is running, but it clearly isn’t healthy — that pattern is often a much stronger signal of trouble than a single, isolated crash.
A rising restart count over a short period is one of the most useful early-warning signals available, often surfacing instability well before it turns into a full outage that users actually notice.
12Security Considerations
Automatic recovery interacts with security in a few subtle but important ways.
Resilience Against Disruption
A restart policy helps a service recover automatically from certain disruptive events, improving overall availability without requiring immediate human response.
Hiding Repeated Exploitation Attempts
If a vulnerability causes a container to crash when exploited, an aggressive restart policy could keep bringing it back up for repeated attempts, without anyone noticing the pattern unless restart counts are actively monitored.
Restart Loops as a Denial-of-Service Risk
A container stuck in a rapid restart loop can consume meaningful CPU and I/O resources on the host, potentially affecting the performance of other, unrelated containers sharing that machine.
13Real-World and Industry Examples
How restart policies show up across everyday production systems.
Small-Team Production Deployments
Teams without dedicated round-the-clock operations staff often rely heavily on restart policies as their first line of defense against downtime, since nobody may be actively watching dashboards at every hour of the day.
Self-Hosted Databases
Database containers running outside of larger managed platforms commonly use “unless-stopped,” ensuring the database survives host reboots and unexpected crashes without requiring manual intervention every time.
Scheduled Batch Processing
Jobs that run on a schedule, process data, and are expected to finish cleanly typically avoid “always,” since restarting a successfully completed job would be both wasteful and potentially harmful if it reprocesses data unnecessarily.
Edge and IoT Deployments
Devices running containers in remote or hard-to-access locations often depend heavily on restart policies, since sending someone physically to manually restart a crashed application may not be practical.
14Frequently Asked Questions
The default is “no” — meaning the container will never be automatically restarted under any circumstances, and will simply stay stopped after it exits or crashes.
Yes — the restart policy of an existing container can generally be updated without needing to recreate the container entirely, though the specific mechanism depends on the tooling in use.
No — restart policies only apply to a container that still exists but has stopped. Once a container is explicitly removed, it no longer exists at all, and no restart policy can bring back something that has been deleted.
No — a restart policy only decides whether and when to start the container again. It has no awareness of, and no effect on, whatever underlying issue is actually causing the crashes in the first place.
No — unlike “on-failure,” which supports a configurable maximum retry count, “always” and “unless-stopped” will keep restarting the container indefinitely, with no built-in limit on the number of attempts.
The core idea — automatically recovering a failed process — carries over, but larger orchestration systems typically have their own, more advanced restart and scheduling logic that operates at a broader level than a single container’s policy.
15Summary and Key Takeaways
Restart Policies give Docker containers the ability to recover from crashes, unexpected exits, and host reboots without waiting for a human to notice and intervene. The four options — no, on-failure, always, and unless-stopped — each serve a distinct purpose, ranging from complete manual control to fully automatic, indefinite recovery. Choosing the right one depends on understanding the nature of the workload: whether it’s meant to run forever or finish once, and whether a deliberate, manual stop should ever be treated as final. Used thoughtfully, and paired with real monitoring rather than as a replacement for it, restart policies become one of the simplest, most effective reliability tools available in Docker.
Key Takeaways
- A restart policy is an automatic recovery rule — attached to a container at launch time, telling Docker what to do after it stops.
- There are four options — no, on-failure, always, and unless-stopped — each fitting a different kind of workload.
- “On-failure” checks the exit code — restarting only when the process genuinely failed, not when it exited cleanly on purpose.
- “Always” and “unless-stopped” look similar but differ on manual stops — only “unless-stopped” respects a deliberate stop across a host reboot.
- Retry limits and increasing delays prevent runaway crash loops — protecting the host from wasted resources when a container is truly broken.
- Restart policies mask symptoms, not root causes — they should be paired with real monitoring, not treated as a substitute for it.
- A rising restart count is an early-warning signal — often revealing instability long before it becomes a visible outage.