How to Implement Docker Restart Policies? [4 Simple Restart Policies]


Here is how to implement Docker restart policies:

    1. No Restart Policy: Set up your Docker container to not restart automatically by running docker run --restart=no [IMAGE], perfect for containers used in temporary tasks or batch jobs that need manual control over start and stop.
    2. Always Restart Policy: Configure your Docker container to always restart if it stops by using docker run --restart=always [IMAGE], ensuring it remains running for critical applications requiring minimal downtime.
    3. Unless-stopped Restart Policy: Implement this policy by running docker run --restart=unless-stopped [IMAGE], which keeps the container running automatically unless you explicitly stop it, ideal for maintaining service continuity through reboots unless manually halted.
    4. On-failure Restart Policy: It restarts a container only if it exits with an error (non-zero exit status), using the command docker run --restart=on-failure [OPTIONS] IMAGE [COMMAND] [ARG…] to maintain service reliability without unnecessary restarts.

    Are you finding it tricky to manage when and how your Docker containers restart? If you juggle different environments, setting the right restart policies is essential for keeping everything running smoothly. In this post, I’ll break down Docker’s restart policies like no, always, on-failure, and unless-stopped, giving you clear, actionable steps to implement them effectively. We’ll tackle common issues together and I’ll share some best practices to make sure your Docker setups are as reliable and efficient as possible. Ready to get your Docker containers dialed in just right? Let’s get started!

    What are Docker Restart Policies?

    Docker restart policies determine how Docker containers should handle restarts under different circumstances, such as after crashes or when the system reboots. Setting a restart policy is essential for managing container operations efficiently, especially in production environments where automatic recovery from failures is crucial.

    Here are the four most common Docker restart policies:

    1. No: As Docker’s default policy, it does not restart containers after they stop, ensuring they remain inactive unless manually restarted. This policy is particularly valuable in development settings, where developers need to manually control when containers run to facilitate debugging and troubleshooting without dealing with automated restarts interfering with the process.
    2. Always: This policy ensures that Docker will automatically restart the container no matter the reason for its stop—be it crash or manual termination. It’s especially crucial for critical services that must stay running continuously, like key web servers or databases, providing a guarantee of maximum uptime and resilience in production environments.
    3. On-failure: Docker applies this restart policy specifically when containers exit due to an error indicated by a non-zero exit status. This approach is essential in environments where reliability is crucial, allowing containers to attempt auto-recovery from errors while providing the option to set a limit on restart attempts to prevent endless restart loops.
    4. Unless-stopped: Under this policy, Docker will restart the container automatically if it stops unexpectedly or during a system reboot, unless it has been manually stopped by the operator. This balance is perfect for maintaining operational continuity without overriding user interventions, making it ideal for environments where manual control over restarts is sometimes necessary.

    How to Implement Docker Restart Policies?

    To implement Docker restart policies, use the docker run --restart=POLICY command, selecting no, always, on-failure, or unless-stopped as the POLICY. For example, docker run --restart=always [OPTIONS] IMAGE [COMMAND] [ARG...] ensures continuous operation, while docker run --restart=on-failure [OPTIONS] IMAGE [COMMAND] [ARG...] restarts only after failures.

    That was a brief overview. For a detailed step-by-step guide on implementing Docker restart policies, continue reading below:

    1. No Restart Policy

    The no-restart policy is used when you want full control over when your container starts and stops. This policy is ideal for containers that don’t need to run continuously or for those that should not restart automatically under any circumstances, such as temporary workloads or batch jobs. Follow these steps to use this policy:

    1. Start by opening your command line interface.
    open terminal
    1. Use the Docker run command to start your container with the no restart policy. Type the following command:
    sudo docker run --restart=no [IMAGE]

    Replace [IMAGE] with the name of the Docker image you want to use.

    starting docker container with no restart policy
    1. You can list the running containers using the command
    sudo docker ps

    Know the status of container before applying any policy.

    listing running docker containers
    1. Once your container is running, you can stop it using:
    sudo docker stop [CONTAINER_ID]

    Stops the running container manually.

    manually stop docker container
    1. After stopping, check that it does not restart automatically. You can list the running containers using:
    sudo docker ps

    Lists the current Docker containers to show their status, verifying that the stopped container hasn’t restarted.

    verifying the container is stopped

    2. Always Restart Policy

    The always restart policy ensures that your container restarts automatically if it ever stops. This is useful for critical applications that must have minimal downtime. Here is how to use this restart policy:

    1. Launch your Terminal window and start your container with the always restart policy by entering:
    sudo docker run --restart=always [IMAGE]

    Replace [IMAGE] with your desired Docker image.

    starting docker container with always restart policy
    1. To verify that the container is in a running state, use the command:
    sudo docker ps
    verifying that the container is in running state
    1. If you want to test whether the always restart policy works as expected (excluding manual stops), you can simulate a crash or an error within the container that causes it to exit abnormally. For instance:
    sudo docker exec [CONTAINER_ID] /bin/sh -c 'kill 1'

    This command sends a signal to terminate the main process inside the container, simulating a crash.

    simulating a crash in the container process
    1. Check that it restarts automatically using:
    sudo docker ps

    Confirm that the container is running again after being stopped.

    check the container started automatically

    3. Unless-stopped Restart Policy

    This policy is used when you want your container to generally restart automatically, unless you have explicitly stopped it. It’s great for ensuring that services resume after reboots unless they’ve been manually deactivated. Here is the step-by-step guide to implement this policy:

    1. Open your Terminal and use this command to run your container with the unless-stopped restart policy:
    sudo docker run --restart=unless-stopped [IMAGE]

    Replace [IMAGE] with the Docker image of your choice.

    starting a container with restart unless stopped policy
    1. After the container starts, stop it using:
    sudo docker stop [CONTAINER_ID]

    Replace the [CONTAINER_ID] with the docker id of your choice.

    stopping docker container
    1. Reboot your system by running the command:
    sudo systemctl restart docker

    It will restart the docker service.

    restarting docker service
    1.  Now check that the container does not restart with the command:
    sudo docker ps

    Shows all Docker containers to confirm that the manually stopped container remains stopped even after a system reboot.

    checking the container is not started automatically

    4. On-failure Docker Restart Policy

    The on-failure restart policy is designed to restart your Docker container only when it exits due to an error, indicated by a non-zero exit status. This targeted approach helps maintain service reliability without burdening the system with unnecessary restarts. Follow these steps:

    1. Before you begin, open your Terminal and run your container with the On-failure policy:
    2. To set up the on-failure restart policy when you run a new container, use the command:
    docker run --restart=on-failure [OPTIONS] IMAGE [COMMAND] [ARG…]

    Replace [OPTIONS] with any Docker options you need, IMAGE with the Docker image you are using, and [COMMAND] [ARG…] with the command and any arguments that the container should execute.

    docker on failure policy

      4 Best Practices for Docker Restart Policies

        Implementing effective Docker restart policies helps ensure your applications run smoothly and recover from failures automatically. It’s important to understand and apply these practices to manage your containers efficiently. Here are four best practices to follow:

        • 🔄 Choose the Right Policy: Select a restart policy that aligns with the container’s role. Use always for crucial services to ensure constant availability. Opt for no or on-failure during development or for non-critical applications, providing greater control over when containers restart.
        • 🔁 Set a Retry Limit: Apply a retry limit with the on-failure policy to prevent endless restart attempts that can strain your system. For example, setting on-failure:3 restricts Docker to three restart attempts, helping to manage resources effectively and maintain system stability.
        • 💾 Protect Your Data: Utilize Docker volumes to keep data separate from containers. This protects your data from being lost or corrupted during restarts or deletions, ensuring data continuity and integrity across various operational scenarios.
        • 📑 Document Your Configuration: Always keep a clear record of your restart policy settings and the reasons for choosing them for each container. This documentation makes it easier to troubleshoot problems and ensures everyone on your team understands and can maintain consistency, no matter where the container runs.

        Final Thoughts

        In this guide, I’ve gone through the steps to implement Docker restart policies correctly. Some best practices to follow when implementing Docker restart policies, such as choosing specific policies for different needs and integrating health checks, will really help you get the most out of your Docker setups.

        If you are looking to improve your Docker expertise, consider exploring topics such as learning to fix the “Command Not Found: Docker Compose” error is crucial for managing multi-container setups. Additionally, mastering how to list Docker containers can improve the management of large systems. Also, understanding how to add a user to the Docker group will aid in creating a secure and collaborative environment.

        Frequently Asked Questions

        1. What happens if Docker itself crashes or restarts—do restart policies still apply?

          When Docker crashes or the system reboots, restart policies automatically apply. Containers configured with restart policies like always or unless-stopped will be restarted by Docker when it comes back up, assuming the system’s conditions allow it.

        2. How can you temporarily disable a restart policy without changing Docker configuration files?

          To temporarily disable a restart policy, use the Docker update command to modify a running container’s policy. For instance, docker update --restart=no [CONTAINER_ID] changes the policy to no, stopping automatic restarts without altering the Dockerfile or configuration files permanently.

        3. Are there any specific log files that can help diagnose issues with Docker restart policies?

          Docker logs and system logs are vital for diagnosing restart policy issues. Use docker logs [CONTAINER_ID] to see logs specific to a container. Additionally, checking the system logs with journalctl -u docker.service can provide insights into Docker’s behavior and operational issues.

        4. What are the default Docker restart settings if none is specified?

          If no restart policy is specified, Docker defaults to no, meaning containers will not automatically restart when they exit. This default setting ensures that Docker does not attempt to manage container lifecycles without explicit configuration.

        5. What should I do if my Docker container fails to restart automatically?

          If your Docker container doesn’t restart automatically, check if it was manually stopped using docker ps -a. For containers stopped manually, the always or unless-stopped policies won’t restart them. To test restart policies, simulate a failure by running docker exec [CONTAINER_ID] /bin/sh -c 'kill 1, which forces the container to exit and triggers the restart policy.



        Ojash is a skilled Linux expert and tech writer with over a decade of experience. He has extensive knowledge of Linux's file system, command-line interface, and software installations. Ojash is also an expert in shell scripting and automation, with experience in Bash, Python, and Perl. He has published numerous articles on Linux in various online publications, making him a valuable resource for both seasoned Linux users and beginners. Ojash is also an active member of the Linux community and participates in Linux forums.



        Akshat is a software engineer, product designer and the co-founder of Scrutify. He's an experienced Linux professional and the senior editor of this blog. He is also an open-source contributor to many projects on Github and has written several technical guides on Linux. Apart from that, he’s also actively sharing his ideas and tutorials on Medium and Attirer. As the editor of this blog, Akshat brings his wealth of knowledge and experience to provide readers with valuable insights and advice on a wide range of Linux-related topics.

        Share this article
        Shareable URL
        Prev Post

        How to Run Linux Commands in Background [8 Effective Methods]

        Next Post

        10 Best Ways to Use ripgrep Command in Linux

        Read next