Docker Compose Dependency Conditions, Decoded

Docker Compose can create a dependency before its dependent without waiting for that dependency to become healthy. That distinction is central to understanding depends_on.

Long-form depends_on separates four decisions:

• Order: Which service must be created first?
• Condition: What must happen before the dependent starts?
• Restart coupling: Should an explicit Compose operation on the dependency restart the dependent?
• Requirement: Is an unavailable dependency mandatory or only a warning?

A running container is not necessarily ready to handle requests. Docker’s startup-order documentation gives the example of an application starting while its database is still unable to process SQL statements. By default, Compose waits for the container to be running, not for general application readiness. Docker: Control startup and shutdown order

Dependency fields at a glance

The three condition values define when a dependency is satisfied. restart and required modify the relationship; they are not additional readiness conditions. Docker Compose services reference

Short-form depends_on: wait for startup

Short syntax declares an ordering relationship:

services:
  web:
    image: example/web
    depends_on:
      - redis

  redis:
    image: redis:alpine

Compose creates dependency services before their dependents and removes them in dependency order. Short-form depends_on guarantees that the dependency has started before the dependent starts, but it does not wait for the dependency to become healthy. Docker Compose services reference

Here, Redis starts before web. The configuration does not establish that Redis can respond to a command when web starts.

service_started: the long-form equivalent

The long-form service_started condition has the same dependency-satisfaction semantics as short-form depends_on:

services:
  web:
    image: example/web
    depends_on:
      redis:
        condition: service_started

  redis:
    image: redis:alpine

Compose waits for Redis to start, but it does not wait for a healthcheck. “Started” therefore does not establish that a database accepts connections, a cache answers commands, or an HTTP service has finished initializing. Docker Compose services reference

Long form is useful when different dependencies need different conditions or when the relationship also uses restart or required.

service_healthy: wait for the configured healthcheck

service_healthy tells Compose to wait until the dependency is healthy as indicated by its configured healthcheck. Docker Compose services reference

Docker’s PostgreSQL example combines multiple dependency settings:

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started

  redis:
    image: redis

  db:
    image: postgres:18
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s

In this example:

• redis must start.
• db must pass its configured PostgreSQL healthcheck.
• restart: true separately controls what happens to web after certain explicit Compose operations on db.

Compose relies on the configured probe. A passing healthcheck establishes only what that check tests. Docker: Control startup and shutdown order

Docker’s Redis quickstart provides another concrete example:

services:
  web:
    build: .
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

The probe runs redis-cli ping and expects PONG. A healthy result means that this specific check passed; it does not validate every Redis command or application workflow. Docker Compose Quickstart

service_completed_successfully: wait for completion

service_completed_successfully waits for a dependency to finish successfully before starting the dependent:

services:
  app:
    image: example/app
    depends_on:
      setup:
        condition: service_completed_successfully

  setup:
    image: example/setup

The distinction is straightforward:

• service_started waits for startup.
• service_healthy waits for the configured healthcheck.
• service_completed_successfully waits for successful completion.

The Compose reference documents that completion requirement but does not establish broader retry, failure-propagation, or later lifecycle behavior. Docker Compose services reference

restart: true: explicit Compose operations

Within long-form depends_on, restart: true applies to the dependent:

depends_on:
  db:
    condition: service_healthy
    restart: true

If an explicit Compose operation updates or restarts db, Compose also restarts the dependent service. Docker gives docker compose restart as an example. Docker: Control startup and shutdown order

This is not general restart propagation. Docker excludes automated restarts performed by the container runtime after a container dies. The field is also separate from the service-level restart policy. Docker Compose services reference

required: false: warn instead of requiring

Dependencies are required by default. Long-form syntax can mark one as optional:

depends_on:
  metrics:
    condition: service_started
    required: false

When required is false, Compose only warns if the dependency is not started or available. If omitted, required defaults to true. This warning behavior does not guarantee that the application can function without the dependency. Docker Compose services reference

Selection rule

Choose each field independently:

1. Use short form or service_started when startup order is sufficient.
2. Use service_healthy when the dependent must wait for a configured healthcheck.
3. Use service_completed_successfully when the dependency must finish successfully.
4. Add restart: true when explicit Compose-controlled operations on the dependency should restart the dependent.
5. Set required: false when an unavailable dependency should produce a warning rather than remain mandatory.

This keeps startup order, healthcheck status, successful completion, restart coupling, and optionality from being mistaken for the same guarantee.

Sources and further reading

• https://docs.docker.com/compose/how-tos/startup-order
• https://docs.docker.com/reference/compose-file/services
• https://docs.docker.com/compose/gettingstarted