Before the specific setting, let’s understand the relationship it’s describing.

When an application is made up of multiple services — as covered in detail elsewhere — those services are rarely fully independent of one another. A web service typically needs a database service to exist and be reachable before it can properly function. This kind of relationship, where one service genuinely relies on another being available, is called a service dependency. Declaring it explicitly, rather than leaving it to chance, is what depends_on is for.

Without declaring dependencies, Docker has no inherent understanding of which services rely on which others — from its point of view, every service defined together is just as independent as any other, free to start in whatever order happens to be convenient, which is frequently not the order your application actually needs.

Understanding the problem this setting solves makes its purpose much clearer.

Without any dependency information, Docker generally starts every defined service at roughly the same time, in no particular guaranteed order relative to one another. For services with no real relationship, this is completely fine. But for a web service that immediately tries to connect to its database the moment it starts, this can easily mean the web service attempts that connection before the database has even begun starting up, resulting in a failed connection and, depending on how the web service handles that failure, potentially a crash right at startup.

sequenceDiagram
    participant Web as Web Service
    participant DB as Database Service

    Note over Web,DB: Both told to start at roughly the same time
    Web->>DB: Attempts connection immediately
    Note over DB: Still starting up, not ready yet
    DB-->>Web: Connection fails
        

This kind of failure is often intermittent and confusing, since the exact timing can vary from one startup to the next — sometimes the database happens to be ready in time purely by chance, and sometimes it isn’t, making the problem seem to appear and disappear randomly rather than consistently.

A precise, careful description of exactly what this setting does.

Declaring that one service depends on another tells Docker to control the order in which their containers are created and started, ensuring the depended-upon service is instructed to start first. It also affects the reverse direction when stopping the application: services are generally stopped in the opposite order, so a service isn’t abruptly cut off from something it still depends on while it’s still in the process of shutting down.

This is a genuinely useful guarantee about ordering. But it’s important to be precise about exactly what “started first” means here, because it’s narrower than many beginners initially assume — a distinction significant enough that the entire next chapter is dedicated to it.

This is the single most important, and most commonly misunderstood, aspect of dependency declarations.

By its most basic behavior, depends_on only guarantees that a depended-upon service’s container has been told to start before the dependent service’s container is started. It does not, on its own, guarantee that the depended-upon service has actually finished its own internal startup process and is genuinely ready to accept connections or requests. A database container can be “started,” in the sense that its process has begun running, while it’s still in the middle of its own internal setup — initializing its storage, preparing to accept connections — and not yet truly ready to be used.

flowchart TD
    A["Database container told to start"] --> B["Process begins running"]
    B --> C["Database performs internal setup"]
    C --> D["Database genuinely ready to accept connections"]
    E["Basic depends_on guarantees B happens before web service starts"] -.-> B
    style D fill:#fef2f2,stroke:#dc2626
        

Fortunately, this gap has a solid solution, which is precisely the subject of the next chapter.

A more precise way of declaring a dependency, going beyond simply “started.”

To address the gap described in Chapter 4, dependency declarations can be made more specific by attaching a condition describing exactly what “ready enough” means for that particular dependency, rather than settling for the basic, looser guarantee of merely having started.

The “service healthy” condition, in particular, directly closes the gap described in Chapter 4 — but it depends entirely on that depended-upon service having a properly defined health check in the first place, since without one, there’s simply no meaningful signal available to wait for.

A meaningful dependency on readiness is only as good as the health check backing it up.

A health check, as covered elsewhere in the context of container states, is a small, repeated test that determines whether a running service is genuinely working correctly, not merely alive. Without one defined for a service, there’s no reliable, structured signal available describing when that service transitions from “just started” to “genuinely ready,” which is exactly why the “service healthy” condition described in Chapter 5 has a real prerequisite behind it.

This connection between health checks and dependency conditions is a good example of how different pieces of a well-designed application definition reinforce one another, rather than existing as separate, unrelated features.

Real applications often involve chains and branches of dependencies, not just a single pair.

Larger applications frequently involve several services with dependencies on one another, forming what’s effectively a small map, or graph, of relationships — a background worker might depend on both a database and a message queue, while a web service depends on that same database and perhaps a caching layer too. Docker examines every declared dependency across the whole application and works out a startup order that respects all of them simultaneously.

flowchart TD
    DB["Database"] --> Web["Web Service"]
    DB --> Worker["Background Worker"]
    Queue["Message Queue"] --> Worker
    Cache["Cache"] --> Web
        

In a graph like this, the database and the message queue, having no dependencies of their own, would be started first, followed by the web service and the background worker once their own respective dependencies are satisfied, with the cache also starting early since nothing depends on it existing beforehand.

One particular shape of dependency graph simply cannot be resolved.

A circular dependency occurs when a chain of dependencies loops back on itself — service A depends on service B, which in turn depends on service A. This creates a genuine logical impossibility: there’s no valid order in which both requirements can be satisfied simultaneously, since each one needs the other to go first.

flowchart LR
    A["Service A"] -->|"depends on"| B["Service B"]
    B -->|"depends on"| A
    style A fill:#fef2f2,stroke:#dc2626
    style B fill:#fef2f2,stroke:#dc2626
        

Two complementary approaches to handling the same underlying uncertainty, each with a different role.

Even with a carefully declared, condition-based dependency, real-world timing can still occasionally be tighter than expected — a health check might report healthy just moments before a service actually becomes fully stable, or a brief network hiccup might cause an otherwise well-timed connection attempt to fail anyway. Many resilient applications handle this final layer of uncertainty with their own internal retry logic, attempting a failed connection again after a short pause rather than giving up or crashing immediately.

The most resilient applications treat these two approaches as complementary rather than as alternatives — depends_on handles the predictable, common-case ordering problem cleanly, while application-level retry logic provides a genuine safety net for the rarer, tighter edge cases that ordering alone can’t fully guarantee against.

How declared dependencies interact with a service running as several containers at once.

As explored in the context of defining services, a single service definition can be scaled to run as multiple identical containers. When a scaled service depends on another, the dependency relationship still applies consistently — the depended-upon service is still started (and, with the right condition, confirmed ready) before any of the dependent service’s multiple containers are started, regardless of how many of them there are.

A few recurring, sensible ways real applications organize their declared dependencies.

What to look at when an application isn’t starting up the way you expect.

When a multi-service application fails to start correctly, checking the current state of each service — whether it’s running, exited, or stuck restarting, as discussed elsewhere regarding container states — combined with its exit code and logs is usually the fastest path to understanding what actually went wrong. Specifically for dependency-related problems, it’s worth checking whether a depended-upon service ever actually reached a healthy status at all, or whether it was still merely “started” when a dependent service gave up trying to connect.

A dependent service that keeps crash-looping shortly after startup, as discussed elsewhere, is a common symptom worth checking against exactly this kind of dependency timing problem, especially if the crashes cluster tightly around the very beginning of the application’s startup sequence.

A short checklist for declaring dependencies that genuinely hold up in practice.

Declared service dependencies show up as a foundational, everyday practice across nearly every multi-service application.

Not by default — as explained in Chapter 4, the basic condition only guarantees the database’s container was told to start first. Use the “service healthy” condition from Chapter 5 for a genuine readiness guarantee.

As covered in Chapter 6, the depended-upon service needs a properly defined health check — without one, there’s no meaningful signal to wait for.

No — as explained in Chapter 8, this creates a circular dependency with no valid resolution, and usually signals a design issue worth addressing directly.

Yes — as noted in Chapter 3, services are generally stopped in roughly the reverse of their declared startup order.

The dependency only needs to be satisfied once — as explained in Chapter 10, all of the scaled service’s containers benefit from the same underlying guarantee before starting.

Yes — as discussed in Chapter 9, retry logic provides a genuine safety net against tight timing edge cases that ordering alone can’t fully guarantee against.

depends_on gives Docker explicit knowledge of the real relationships between your application’s services, turning what would otherwise be an unpredictable, potentially race-prone startup order into something deliberate and reliable. Its basic form guarantees only that a depended-upon service has been told to start first, a distinction genuinely worth internalizing, since true readiness requires pairing the dependency with a condition based on a proper health check. Understood correctly, alongside its interaction with dependency graphs, scaling, and application-level retry logic as a complementary safety net, depends_on becomes one of the most practical tools for making a multi-service application start up the same reliable way, every single time.