Restart Containers In Docker Compose

The short answer

In Docker Compose, to restart all the containers related to all the services defined in the [.inline-code]compose.yaml[.inline-code] file of your project at once, you must first navigate to the directory containing that configuration file, then use the [.inline-code]docker compose restart[.inline-code] command:

 $ docker compose restart

Note that this command will not rebuild the containers or pull updated images; it will only stop and restart the existing containers.

You can learn more about restarting individual containers by reading our article on how to restart single containers in Docker.

[#restart-specific-services] Restarting the containers of one or more services [#restart-specific-services]

To restart the containers associated with one or more specific services, you can use the following command:

 $ docker compose restart <service_name …>

Where [.inline-code]service_name …[.inline-code] is a list of service names separated by a space character.

For example, this command will restart the containers of the [.inline-code]website[.inline-code] and [.inline-code]api[.inline-code] services:

 $ docker compose restart website api

[#restart-with-a-timeout] Restarting containers with a timeout [#restart-with-a-timeout]

By default, when executing the [.inline-code]docker compose restart[.inline-code] command, all the containers associated with the specified services are immediately killed by Compose before being restarted.

To allow these containers to stop gracefully, you can specify a restart delay, called a timeout,  expressed in seconds using the [.inline-code]-t[.inline-code] flag (short for [.inline-code]--timeout[.inline-code]):

 $ docker compose restart -t <seconds> [<service_name …>]

Note that if the containers don't stop within the specified timeout, Compose will forcefully terminate them.

For example, the following command will give 90 seconds to the [.inline-code]api[.inline-code] service to perform its cleanup tasks and gracefully exit before being restarted by Compose:

 $ docker compose restart -t 90 api

[#easily-recall-with-ai] Easily retrieve these commands using Wrap’s AI Command Suggestions [#easily-recall-with-ai]

If you’re using Wrap as your terminal, you can easily retrieve these commands using the Wrap AI Command Suggestions feature:

Entering [.inline-code]docker compose restart options[.inline-code] in the AI Command Suggestion will prompt a list of [.inline-code]docker[.inline-code] commands that can then quickly be inserted into your shell by pressing [.inline-code]CMD + ENTER[.inline-code].

[#rebuild-on-configuration-change] Rebuilding containers on configuration or image change [#rebuild-on-configuration-change]

To automatically stop, remove, and rebuild all the containers associated with all the services defined in the [.inline-code]compose.yaml[.inline-code] file whose configuration or image have changed, you can use the [.inline-code]docker compose up[.inline-code] command:

 $ docker compose up

Alternatively, if you only want to rebuild the containers associated with specific services, you can use the following syntax instead:

 $ docker compose up <service_name …>

Where [.inline-code]service_name …[.inline-code] is a list of service names separated by a space character.

[#rebuild-without-dependencies] Rebuilding containers without dependencies [#rebuild-without-dependencies]

By default, when rebuilding a service that depends on other services, the dependent services will also be automatically rebuilt by Compose.

To prevent this behavior and rebuild the desired services only, you can use the [.inline-code]docker compose up[.inline-code] command with the [.inline-code]--no-deps[.inline-code] flag as follows:

 $ docker compose up --no-deps <service_name …>

You can learn more about service dependencies by reading our article on understanding the depends_on property in Docker Compose.

[#rebuild-forcefully] Rebuilding containers forcefully [#rebuild-forcefully]

To rebuild the containers associated with specific services regardless of a configuration or image change, you can use the [.inline-code]docker compose up[.inline-code] command with the [.inline-code]--force-recreate[.inline-code] flag as follows:

 $ docker compose up --force-recreate <service_name …>

[#define-restart-policies] Defining the restart policy of containers [#define-restart-policies]

In Docker Compose, you can use restart policies to define how your containers should behave in case of termination or failure.

These policies are defined through the [.inline-code]restart[.inline-code] property and take one of the following values:

• [.inline-code]no[.inline-code]: The default restart policy. It does not restart the container under any circumstances.
• [.inline-code]always[.inline-code]: The policy always restarts the container until its removal.
• [.inline-code]on-failure[.inline-code]: The policy restarts the container if the exit code indicates an error.
• [.inline-code]unless-stopped[.inline-code]: The policy restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed.

 services:
  <service_name>:
    image: <image_name>
    restart: <policy>

For example, the following configuration will try to restart the container of the [.inline-code]api[.inline-code] service for a maximum of 3 times on failure:

 services:
  api:
    build: ./api
    restart: on-failure:3

You can learn more about restart policies for single containers by reading our article on how to restart a Docker container.

[#restart-with-health-checks] Restarting unhealthy services using a health check [#restart-with-health-checks]

In Docker Compose, the [.inline-code]healthcheck[.inline-code] property allows you to define a test command to periodically check the health of a container. It is often combined with the [.inline-code]restart[.inline-code] property to define under which condition a service should restart whenever it becomes unhealthy.

 services:
  <service_name>:
    image: <image_name>
    healthcheck:
      test: <command>

For example, the following configuration checks whether the container of the [.inline-code]webserver[.inline-code] service is healthy by sending an HTTP request to the [.inline-code]nginx[.inline-code] server located at the [.inline-code]localhost[.inline-code] address:

 services:
  webserver:
    image: nginx
    healthcheck:
      test: "curl -f http://localhost"

You can learn more about health check by reading our article on understanding the healthcheck property in Docker Compose.