Understanding Restart Policies for Docker Containers


Docker has become an essential tool for developers, streamlining the process of building, packaging, and deploying applications as lightweight, portable containers. Restart policies play a crucial role in managing the lifecycle of Docker containers, dictating how containers respond to failures, crashes, or system reboots.

This article will explore the available restart policies in Docker, their implications, and how to choose the right one for your application.

Restart Policies in Docker

A restart policy determines the behavior of a Docker container when it exits, either due to a crash, an error, or a system restart. Docker offers four restart policies:

  1. no
  2. on-failure
  3. always
  4. unless-stopped

No Restart Policy (no)

The ‘no’ policy is the default policy if none is specified when starting a container. When a container exits, Docker does not attempt to restart it, regardless of the exit status. This policy is ideal for short-lived containers, such as those running batch jobs or one-time tasks.


docker run --restart=no your-container-image

Restart on Failure Policy (on-failure)

With the ‘on-failure’ policy, Docker restarts a container only if it exits with a non-zero status. This policy is useful for long-running applications that need to recover from unexpected crashes or errors.

Optionally, you can specify the maximum number of restart attempts using the :max-retries flag. If the container continues to fail after the specified number of attempts, Docker will not restart it again.


docker run --restart=on-failure your-container-image
docker run --restart=on-failure:5 your-container-image

Always Restart Policy (always)

The ‘always’ policy ensures that a container is always restarted, regardless of the exit status. It is useful for critical applications that must be constantly available.

If a container is manually stopped, it will be restarted automatically when the Docker daemon starts up again, such as after a system reboot.


docker run --restart=always your-container-image

Restart Unless Stopped Policy (unless-stopped)

The ‘unless-stopped’ policy restarts a container under any circumstances, except when it has been manually stopped by the user or the Docker daemon itself. This policy is ideal for services that need to run continuously but can be stopped for maintenance or updates.


docker run --restart=unless-stopped your-container-image

Choosing the Right Restart Policy

Selecting the appropriate restart policy for your container depends on your application’s requirements and expected behavior. Consider the following questions when making your decision:

  • Is the container short-lived or long-running?
  • Does the application need to recover from unexpected crashes or errors?
  • Should the container restart automatically after a system reboot?
  • Can the container be stopped for maintenance or updates?


Restart policies are essential in managing the lifecycle of Docker containers, ensuring that applications remain available and resilient in the face of failures. Understanding the available policies and their implications is crucial for making informed decisions about your container’s behavior. Be sure to consider the specific requirements of your application when choosing a restart policy to guarantee optimal performance and reliability.

Related Articles