📦 wslc-compose
v0.6.0 · Python ≥ 3.9 · MIT Works with the WSL container preview today

docker-compose for
WSL containers

Microsoft's new wslc CLI runs containers natively on Windows — but has no Compose support yet. wslc-compose drives it from the compose.yaml you already use with Docker or Podman. No daemon, no lock-in.

$ pipx install "wslc-compose==0.6.0"

Latest release PyPI version Available on PyPI — also uv tool install "wslc-compose==0.6.0".
On Debian/Ubuntu (externally-managed-environment) or without pipx, use the one-line installer.

Install from PyPI Quick start Migrate an existing wslc setup
Terminal — WSL
$ cd my-project              # contains the same compose.yaml as your Docker setup
$ wslc compose up -d
Network my-project_default created
Volume my-project_data created
Creating my-project-db-1 ...
Creating my-project-web-1 ...

$ wslc compose ps
NAME               SERVICE  IMAGE         STATUS   PORTS
my-project-db-1    db       postgres:16   running
my-project-web-1   web      nginx:alpine  running  0.0.0.0:8080->80/tcp

$ wslc compose logs -f web
$ wslc compose exec web sh
$ wslc compose down -v

$ wslc images                 # not a compose command → forwarded verbatim to wslc.exe

New in 0.6

Closer to Docker Compose on every compose file, and a project that keeps going when one service fails. Upgrading recreates nothing: the shared config hash is unchanged.

one taken port no longer stops the project
$ wslc compose up -d
Creating my-project-api-1 ...
Creating my-project-web-1 ...
wslc-compose: Container my-project-web-1 failed to start: wslc run -d failed (exit 1)
Creating my-project-worker-1 ...
wslc-compose: 1 service failed to start: web   # the others run; exit status 1
🧬

extends & merge tags

extends: (same file or file:), !reset / !override, nested ${A:-${B}}, YAML 1.2 booleans like Compose.

📄

env files that just work

export, quotes, # comments, required: false; editing an env file recreates the container.

🔌

Ports & mounts

127.0.0.1::80, IPv6 [::1]:8080:80, tmpfs size/mode translated to wslc's mount options.

✅

100% tested

Every line and branch covered on Linux and Windows, enforced in CI; each fix checked on a live wslc session.

No daemon. No state file. No magic.

A thin Python CLI (one dependency: PyYAML) that turns your compose file into plain wslc commands.

1

Load

Finds your compose.yaml / docker-compose.yml, applies .env and ${VAR:-default} interpolation exactly like docker compose, and normalizes it.

2

Plan

Which networks and volumes must exist, which images to build or pull, the depends_on start order, and which containers are stale (config-hash comparison).

3

Execute

Plain wslc run / build / network create / ... invocations. Add --dry-run to any command to see them verbatim — and paste them yourself if you prefer.

State lives entirely in wslc (container labels), so wslc-compose and the raw wslc CLI mix freely. When WSL ships native Compose support (microsoft/WSL#40948), migrating away is trivial — your compose files never stopped being standard compose files.

Everything you expect from compose

Mapped onto the wslc preview — including the parts that are easy to get wrong by hand.

🌐

Networks with DNS

Per-project networks; services resolve each other by name and alias, so db:5432 URLs work unchanged.

💾

Volumes & bind mounts

Named volumes created on demand; Linux bind-mount paths translated to the Windows paths wslc requires (wslpath -w) automatically.

🧱

Builds

build: with context, dockerfile, args, target — images tagged <project>-<service>, rebuilt only when missing or on --build.

🔀

Dependency ordering & health

depends_on start order, plus condition: service_healthy and service_completed_successfully — up waits for the database to be ready before starting the app. Optional dependencies with required: false.

♻️

Config-drift detection

up is idempotent: it recreates only the services whose resolved configuration actually changed, and leaves the rest running.

📈

Scaling & profiles

deploy.replicas, --scale svc=N, compose profiles, project scoping — several projects coexist cleanly.

🖥️

Familiar UX

up · down · ps · logs -f · exec · build · pull · config — plus a wslc wrapper so it feels exactly like docker compose.

🔍

Transparent

--dry-run on any command prints every wslc invocation. Unsupported keys warn instead of failing, so existing files keep working.

🩺

Healthchecks

healthcheck is mapped to wslc --health-* options and shown by ps as (healthy) / (unhealthy).

📦

Multiple files & include

Overlay files with repeated -f or COMPOSE_FILE, and split big projects with include:, like docker compose.

🔐

Secrets & configs

File-backed secrets and configs are mounted read-only into containers; multiple networks with static IPs and aliases are supported too.

🚑

Preview-proof docs

The sharp edges of the wslc preview — per-elevation sessions, mount limits, wedged sessions — documented with tested recovery steps.

Compose file compatibility

A sample of the mapping — the full table is in the README. Keys wslc can't honor yet are accepted with a warning, never a failure.

Compose keyHandled as
image, build✓  wslc run / wslc build -t project-service
ports (short/long, ranges, udp)✓  -p
volumes (named, bind, tmpfs, :ro)✓  -v with Windows-path translation
networks, aliases, external✓  wslc network create, --network-alias
environment, env_file, ${VAR}✓  full docker-compose interpolation rules
depends_on, deploy.replicas, profiles✓  ordering, service_healthy / completed_successfully waits, scaling, opt-in services
healthcheck✓  --health-cmd, --health-interval, …
secrets, configs (file-backed), include✓  read-only mounts, per-file path rebasing
restart: always, cap_add, cap_drop✓  --restart, --cap-add/--cap-drop with wslc ≥ 3.0.5
privileged, devices, restart: unless-stopped, …⚠  no wslc equivalent yet — warned, not fatal

Already running containers with raw wslc run? The migration guide covers the move end to end: image retagging instead of rebuilds, port handover, verification from the Windows loopback, rollback — plus a recovery cheat sheet for the preview's sharp edges.