Docker Compose Restart: Policies and Commands (2026)

There are two different things people mean by "docker compose restart": the command you run to restart running services, and the restart policy that decides whether containers come back automatically after a crash or reboot. This guide covers both.

The restart command

# Restart every service in the stack
docker compose restart

# Restart a single service
docker compose restart web

docker compose restart stops and starts the existing containers. It is quick, but note the catch below.

Important: docker compose restart does not pick up changes to your docker-compose.yml or .env. It restarts the containers as they are. To apply config changes, use docker compose up -d instead — it recreates only the services that changed.

Command	Picks up config changes?	Use when
docker compose restart	No	Bounce a service quickly
docker compose up -d	Yes	You edited the Compose file or env
docker compose down && up -d	Yes (full recreate)	You want a clean rebuild

---

Restart policies

A restart policy tells Docker what to do when a container exits. Set it per service with the restart key.

services:
  web:
    image: nginx
    restart: unless-stopped

The four values:

Policy	Restarts on crash?	Restarts after reboot?	Respects manual stop?
no (default)	No	No	—
on-failure	Only on non-zero exit	Only if it had failed	—
always	Yes	Yes	No — restarts even if you stopped it
unless-stopped	Yes	Yes	Yes — stays stopped if you stopped it

Which one to use

• unless-stopped — the right default for most long-running services. It survives crashes and host reboots, but if you deliberately stop it, it stays stopped.
• always — like unless-stopped, except it also restarts a container you manually stopped (on daemon restart). Rarely what you want.
• on-failure — good for jobs that should retry only when they exit with an error. You can cap attempts: on-failure:5.
• no — for one-off tasks that should run once and stay down.

services:
  worker:
    build: .
    restart: on-failure:5   # retry up to 5 times on error

---

Why won't my container stay up?

If a service keeps restarting in a loop, the restart policy is doing its job — the container is crashing and being brought back. Look at the logs, not the policy:

docker compose logs -f web
docker compose ps        # shows "Restarting" status

Common causes: the app exits immediately (wrong command), a missing env var, or a dependency (like a database) not being ready yet.

---

Restart policy vs depends_on

restart handles crashes; it does not handle start order. If web needs db to be ready first, combine a restart policy with a healthcheck and depends_on: condition: service_healthy. To keep your data across restarts, make sure the service uses a named volume. For starting the whole stack automatically on a server boot, see start Docker on boot.

---

Restarts you don't have to think about

On Hostim.dev, crashed apps are restarted and kept healthy automatically — no restart: policy to tune, and rolling redeploys avoid downtime.

👉 Deploy an app that stays up on its own

Frequently asked questions

What is the difference between docker compose restart and docker compose up?

'docker compose restart' stops and starts the existing containers as they are and does not pick up changes to your docker-compose.yml or .env. 'docker compose up -d' recreates the services that changed, so it applies config edits. Use restart to bounce a service quickly and up -d after editing configuration.

What is the difference between always and unless-stopped restart policy?

Both restart a container after a crash and after a host reboot. The difference is manual stops: with 'always', a container you stopped by hand will be started again when the Docker daemon restarts, while 'unless-stopped' leaves it stopped. 'unless-stopped' is the safer default for most services.

How do I restart a single service in Docker Compose?

Run 'docker compose restart <service>', for example 'docker compose restart web'. This restarts only that service's container without touching the rest of the stack. If you changed configuration, use 'docker compose up -d <service>' instead so the change is applied.

Which restart policy should I use in Docker Compose?

Use 'unless-stopped' for most long-running services — it survives crashes and reboots but respects a manual stop. Use 'on-failure' (optionally with a retry limit like 'on-failure:5') for jobs that should retry only on error, and 'no' for one-off tasks that should run once.