Compose depends_on on wslc

Updated 2026-07-27 · 4 min read · wslc public preview

Compose's depends_on has no equivalent in wslc 2.9.4.0. There is no flag to translate it into, so a faithful migration is impossible -- the workload has to be restructured, or the key dropped and its effect achieved another way. This page documents what we measured and the closest working alternative.

Measured caveat. No dependency ordering. Start services in order yourself and add readiness waits.

The Compose input

A minimal service that uses depends_on. Everything below is derived from this snippet, so you can match it against the shape of your own file.

services:
  api:
    image: node:22-alpine
    depends_on:
      db:
        condition: service_healthy

There is nothing to translate

wslc 2.9.4.0 has no flag that carries depends_on, so the key cannot be migrated faithfully. Dropping it silently changes how the workload runs. The closest working alternative:

# Start the dependency first, then gate on its health state.
wslc run -d --name proj-db --health-cmd "pg_isready -U postgres" \
  --health-interval 5s --health-retries 10 postgres:16-alpine

while ($true) {
  $state = wslc container list --filter name=proj-db --format json | ConvertFrom-Json
  if ($state.Health -eq 'healthy') { break }
  Start-Sleep -Seconds 2
}

wslc run -d --name proj-api node:22-alpine

How we know

We verified this by running the flag against wslc 2.9.4.0 on a Windows Server 2025 runner rather than reading documentation. Unknown flags fail loudly -- wslc answers Argument name was not recognized for the current command and exits non-zero -- so a silent misconfiguration is unlikely. The risk is the opposite one: assuming a Docker habit carries over, scripting it, and only discovering at run time that the container never had the property you asked for.

Claims on this site are re-checked by a scheduled workflow that runs the commands again on a fresh Windows Server 2025 runner and fails when a documented behaviour stops matching reality. wslc ships roughly every two weeks during the preview, so treat any page that disagrees with your own machine as the page being stale, and check the version you are on with wslc version.

Where this key sits in the wider picture

Of the 39 Compose keys we audited against wslc 2.9.4.0, 23 translate directly, 2 translate with a caveat, and 14 have no equivalent at all. That ratio is the honest answer to whether a Compose stack can move to wslc today: simple single-service definitions usually port cleanly, while anything relying on orchestration, capabilities or restart behaviour does not.

Microsoft is tracking native Compose support in issue 40948, opened by a WSL program manager. At the time of writing it carried no milestone, no assignee and no implementation pull request, and the strongest community proposal is to expose a Docker Engine API-compatible endpoint and bundle upstream Compose rather than reimplement it. Either route would change this page from a migration guide into a behaviour-difference reference, which is why the URL will not move.

Full mapping table: Docker Compose to wslc migration guide. Command-level equivalents: Docker to wslc cheat sheet. Paste a whole file into the Compose migration analyser to see every key in it classified at once.

Related guides