9.3.3 Depends On Config

Depends-on config is the depends_on field within a Compose service, declaring which other services that service relies on, used by Compose both to determine a sensible startup order and, optionally, to wait for a dependency to actually be ready before starting the dependent service.

The Simple List Form

The most basic form simply lists the names of services this one depends on.

services:
  api:
    depends_on:
      - db
      - cache
  db:
    image: postgres:16
  cache:
    image: redis:7

Compose starts db and cache before starting api, reflecting this declared dependency.

The Expanded Form With Condition Checking

A more thorough form specifies a condition that must be satisfied before the dependent service starts, rather than simply waiting for the dependency to start.

services:
  api:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 5

This waits specifically for db's health check to report healthy, a meaningfully stronger guarantee than simply waiting for the container to have started.

Available Condition Types

Beyond service_healthy, other condition types support waiting for a service to have simply started, or to have completed successfully (useful for one-off initialization services).

services:
  api:
    depends_on:
      migrate:
        condition: service_completed_successfully
  migrate:
    build: .
    command: npm run migrate

This waits for the migrate service to run to completion successfully before starting api, a pattern well suited to a one-time database migration step.

Why Depends-On Config Matters

Correctly configuring depends_on, including using condition-based waiting where simple startup-order sequencing isn't sufficient, is an important tool for ensuring a multi-service application starts up in a coherent, reliable order.