DevOps Tutorials, Guides & Best Practices

A Docker Compose restart policy tells Docker what to do after a container exits. For most local services that should come back after a reboot, use restart: unless-stopped. For short-lived jobs, use restart: "no". For services where retries should stop after repeated failures, use restart: on-failure:3.

Quick answer: unless-stopped is the safest default for long-running dev or self-hosted services. Use always only when you really want Docker to bring the container back even after manual stops and daemon restarts.

What restart policies do in Docker Compose

In a Compose service, the restart: key is passed to the container runtime. It does not fix a broken application; it only decides whether Docker should start the container again after the process exits.

services:
  web:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "8080:80"Code language: CSS (css)

If you are still building the stack itself, start with the main Docker Compose Up guide. This article focuses only on what happens after a service exits or the Docker daemon restarts.

The four Compose restart policies

Compose supports the same practical restart policy values most Docker users expect: no, always, on-failure, and unless-stopped.

• restart: "no" — the default. Docker does not automatically restart the container.
• restart: always — Docker restarts the container until it is removed. It can also come back after a daemon restart.
• restart: on-failure — Docker restarts the container only when it exits with a non-zero error code.
• restart: on-failure:3 — same as on-failure, but Docker gives up after three failed restart attempts.
• restart: unless-stopped — Docker restarts the container unless you explicitly stopped or removed it.

Recommended defaults

• Use unless-stopped for long-running web apps, APIs, databases in small self-hosted stacks, queues, and monitoring agents.
• Use on-failure for workers where a crash may be transient, but a clean exit should stay stopped.
• Use on-failure:3 when endless retries would hide a real production problem.
• Use "no" for one-off jobs, migrations, seed scripts, and commands that are supposed to exit.

Practical compose.yml examples

A web service that should come back after reboot

services:
  web:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "8080:80"Code language: CSS (css)

This is the common choice for a service you want to keep running across Docker daemon restarts or server reboots, while still respecting a manual stop.

A worker that should retry only after errors

services:
  worker:
    build: ./worker
    command: python worker.py
    restart: on-failure:3

This keeps a flaky worker from disappearing after a transient crash, but it also avoids an infinite restart loop if the error is permanent.

A migration that should not restart

services:
  migrate:
    image: myapp:latest
    command: ./manage.py migrate
    restart: "no"Code language: JavaScript (javascript)

A migration is supposed to finish. Restarting it automatically can repeat work or hide a deployment problem.

restart vs docker compose restart vs deploy.restart_policy

These names are easy to mix up, but they solve different problems.

• restart: in compose.yml is a container runtime policy. It controls automatic restarts after exits or daemon restarts.
• docker compose restart SERVICE is a manual command. It restarts a running service now; it does not define future restart behavior.
• deploy.restart_policy belongs to the Compose Deploy Specification. In normal local Compose usage, prefer the service-level restart: key unless you are intentionally targeting a deploy platform that honors the deploy section.

services:
  api:
    image: myapp/api:latest
    restart: unless-stopped

    # This deploy section is for deployment platforms / Swarm-style behavior.
    # Do not rely on it as a replacement for restart: in ordinary local Compose.
    deploy:
      restart_policy:
        condition: on-failure
        max_attempts: 3Code language: PHP (php)

How to debug restart loops

A restart policy can make a broken service look “alive” from far away. If a container keeps restarting, check the exit state and logs before increasing retries.

docker compose ps
docker compose logs --tail=100 web
docker inspect --format='{{.RestartCount}}' <container_name_or_id>Code language: HTML, XML (xml)

Common causes include missing environment variables, port conflicts, bad credentials, failing health checks, and application crashes during startup. If the problem involves ports, compare it with the troubleshooting section in the Docker Compose Up article.

How restart policies interact with stop, down, and volumes

docker compose stop stops containers but keeps them around. Use stop when you want to pause a stack without removing containers. docker compose down removes containers and default networks; see the Docker Compose Down guide before adding volume-removal flags.

Restart policies do not protect your data. If the service is stateful, the important part is how volumes are configured. For that, use the Docker Compose Volumes guide and avoid deleting named volumes during cleanup.

When not to use a restart policy

• When the service is a one-off job or migration.
• When repeated retries could write duplicate data or trigger duplicate external calls.
• When a failure should page a human or fail a deployment instead of hiding behind automatic restarts.
• When you are debugging startup crashes and need the container to stay stopped long enough to inspect it.

For background on the container lifecycle itself, the Docker Containers guide is the better starting point.

FAQ