Docker ↔ wslc cheat sheet
A single-page reference for translating between the Docker CLI and wslc, the
WSL containers runtime on Windows 11. Colour tells you the risk: green is a
byte-for-byte match, blue changed name only, amber works but behaves differently, red has no
equivalent in the current preview.
For whole scripts, the command converter applies these rules automatically and flags the ones that need a human decision.
Commands
| Docker | wslc | Status | Notes |
|---|---|---|---|
docker run | wslc run | Partial | -d, -p, -v, -e, --name, --rm, -it, -m all exist. No --device, --platform or --restart. Memory units must be uppercase: 512M works, 512m is rejected. |
docker build | wslc build | Partial | Has -t, -f, --build-arg, --target, --no-cache, --pull, -l, --verbose. No --platform, no --secret, no --ssh, no --cache-from. Also available as wslc image build. |
docker pull | wslc pull | Partial | Takes an image name and nothing else: no --platform, no -a, no -q. 10/10 mainstream images pulled and ran in our matrix test. |
docker push | wslc push | Identical | Requires wslc login for private registries. |
docker ps | wslc container list | Renamed | wslc ps also works in 2.9.4.0, so the rewrite is cosmetic. |
docker ps -a | wslc container list --all | Renamed | Use --all to include stopped containers. wslc ps -a works too. |
docker images | wslc image list | Renamed | wslc images also works; both forms are accepted. |
docker rmi | wslc image remove | Renamed | wslc rmi also works. Accepts image ID or tag. |
docker rm | wslc container remove | Renamed | wslc remove works too, with aliases rm and delete. -f forces removal of a running container. |
docker stop | wslc stop | Identical | Has -s/--signal and -t/--time (default 5 seconds, not Docker’s 10). |
docker start | wslc start | Identical | — |
docker restart | (no equivalent) | Not supported | There is no wslc restart in 2.9.4.0, neither top-level nor under the container noun. Run wslc stop <id> then wslc start <id>. |
docker exec | wslc exec | Identical | Has -i, -t, -u, -w, -e, --env-file, -d. Also available as wslc container exec. |
docker logs | wslc logs | Identical | Has -f/--follow, -n/--tail, -t/--timestamps, --since, --until. Note the short form is -n, not Docker’s unabbreviated --tail only. |
docker inspect | wslc inspect | Partial | Only -t/--type; there is no --format, so no Go templates. JSON shape follows OCI, not the Docker schema. |
docker stats | wslc stats | Partial | Prints a one-shot snapshot, not a live stream: there is no --no-stream because it never streams. Has -a, --format json|table, --no-trunc. |
docker cp | wslc container cp | Renamed | There is no top-level wslc cp. The noun form is required. Host paths use Windows syntax. |
docker tag | wslc tag | Identical | — |
docker login | wslc login | Identical | Credentials are stored per Windows user. |
docker system prune | (no equivalent) | Not supported | wslc system only exposes session. Use the per-noun prunes: wslc container prune, wslc image prune, wslc volume prune, wslc network prune. |
docker system df | (no equivalent) | Not supported | No system df and no system info in 2.9.4.0. |
docker volume create | wslc volume create | Partial | Named volumes live inside the utility VM. Bind mounts use VirtioFS. |
docker network create | wslc network create | Partial | Has -d/--driver (default bridge), --subnet, --gateway, --internal, -o/--opt, -l. On wslc run, --network none works but --network host is rejected: "host mode networking is not supported". |
docker pause | (no equivalent) | Not supported | pause, unpause, top, wait, port, rename, diff and commit are all absent in 2.9.4.0. |
docker compose up | (no direct equivalent) | Not supported | No built-in Compose runtime. Translate services to individual wslc run calls or drive them from a script. |
docker swarm | (no equivalent) | Not supported | Orchestration is out of scope for wslc. Use Kubernetes or Docker for swarm workloads. |
docker buildx bake | (no equivalent) | Not supported | Multi-platform bake files are not supported. |
Flags for run and build
| Docker flag | wslc flag | Status | Notes |
|---|---|---|---|
-d, --detach | -d, --detach | Identical | Run in background. |
-p, --publish | -p, --publish | Identical | Reachable on Windows localhost with no extra proxy step. |
-v, --volume | -v, --volume | Partial | Host paths shared over VirtioFS. Use forward slashes: C:/work:/app. |
-e, --env | -e, --env | Identical | Quote values containing spaces. |
--env-file | --env-file | Identical | — |
--name | --name | Identical | The container name is also its DNS name on a user-defined network. |
--rm | --rm | Identical | — |
-it | -it | Identical | Interactive TTY works in Windows Terminal and PowerShell. |
-u, --user | -u, --user | Identical | — |
-w, --workdir | -w, --workdir | Identical | — |
--entrypoint | --entrypoint | Identical | — |
--gpus all | --gpus all | Identical | Same flag. Help text: “Add GPU devices to the container (all to pass all GPUs)”. Fails at container start on a GPU-less host. |
--device | — | Not supported | Not recognized on wslc 2.9.4.0. Use --gpus for GPUs; there is no generic device passthrough. |
--network | --network | Partial | --network none works. --network host is rejected outright: “host mode networking is not supported”. Also has --network-alias. |
--platform | — | Not supported | Host architecture only. No cross-building. |
--restart | — | Not supported | No restart policies. Use a Windows scheduled task. |
--memory | -m, --memory | Partial | Units must be uppercase: 512M is accepted, 512m is rejected. Expect a harmless “kernel does not support swap limit” warning. |
--shm-size | --shm-size | Partial | Same uppercase-unit rule: 64M works, 64m is rejected. |
--cpus | --cpus | Partial | Bounded by the utility VM allocation. |
--health-cmd | --health-cmd | Identical | Health checks are implemented. Also --health-interval, --health-retries, --health-start-period, --health-timeout, --no-healthcheck. |
-P, --publish-all | -P, --publish-all | Identical | Publishes all exposed ports to random host ports. |
--tmpfs | --tmpfs | Identical | — |
--ulimit | --ulimit | Identical | Format <name>=<soft>[:<hard>], -1 for unlimited. |
--stop-signal | --stop-signal | Identical | — |
--stop-timeout | --stop-timeout | Identical | -1 disables the timeout. |
--cidfile | --cidfile | Identical | — |
--dns | --dns | Identical | Also --dns-option and --dns-search. |
--domainname | --domainname | Identical | — |
-l, --label | -l, --label | Identical | — |
--cap-add | — | Not supported | No capability, security-opt or privileged flags on wslc run. |
Conventions that differ
| Topic | Docker Desktop | wslc |
|---|---|---|
| Host path syntax | C:\work:/app or /mnt/c/work:/app | C:/work:/app — forward slashes; a backslash is an escape character |
| Host file sharing | 9p / gRPC-FUSE | VirtioFS, up to 2× faster |
| Published port on Windows | NAT plus port proxy | Direct on host stack; curl.exe localhost:PORT just works |
| VPN and proxy | Needs per-container config | Inherited from Windows automatically |
| Control channel | dockerd over named pipe | Daemonless; host service starts a VM on demand |
inspect output | Docker JSON schema | OCI schema — scripts parsing .NetworkSettings break silently |
| Image store | Shared with Compose, buildx | Separate store; images must be pulled again |
| Idle memory | ~1–2 GB resident | ~0 when no containers run |
Common recipes
# smoke test
wslc run --rm alpine echo ok
# web server, reachable at http://localhost:8080 from Windows
wslc run -d -p 8080:80 --name web nginx:alpine
# interactive shell with the current directory mounted
wslc run --rm -it -v "$($PWD.Path -replace '\\','/'):/app" -w /app node:22 bash
# GPU workload (same flag as Docker)
wslc run --rm --gpus all nvidia/cuda:12.4-base nvidia-smi
# memory limit -- the unit must be uppercase, 512m is rejected
wslc run --rm -m 512M --shm-size 64M alpine sh
# build and tag
wslc build -t myapp:dev .
# user-defined network so containers resolve each other by name
wslc network create appnet
wslc run -d --name db --network appnet postgres:16-alpine
wslc run -d --name api --network appnet -p 3000:3000 myapp:dev
# health check on the container itself (Compose healthcheck: blocks are not read)
wslc run -d --name db --network appnet \
--health-cmd "pg_isready -U postgres" --health-interval 10s --health-retries 3 \
postgres:16-alpine
# logs and stats
wslc logs -f web
wslc stats
# clean up -- there is no wslc system prune, prune per noun
wslc stop web; wslc container remove web
wslc container prune
wslc image prune --all
wslc volume prune
wslc network prune
# no wslc restart either -- stop then start
wslc stop web; wslc start webNot supported at all
These have no wslc path in the public preview. If your workflow depends on one, keep Docker for that project — the two runtimes coexist without conflict.
- Compose — no
wslc compose. See the migration guide, or run your file through the migration analyser. - Swarm, services, stacks, secrets, configs.
- Kubernetes — no bundled cluster.
- buildx / bake and multi-platform builds. There is no
--platformonrun,buildorpull. - Restart policies —
--restartis rejected as an unknown argument, and there is nowslc restartsubcommand either. (Health checks are supported — see the flag table above.) - Windows containers — wslc runs Linux images only.
- Docker socket compatibility — Testcontainers and socket-dependent tooling
will not attach. Note that
-v /var/run/docker.sock:/var/run/docker.sockis accepted and exits 0; the mount just has nothing behind it. wslc system prune,system df,system info— thesystemnoun only hassession. Prune per noun instead.pause,unpause,top,wait,port,rename,diff,commit— none of these exist in 2.9.4.0.--device,--cap-add,--security-opt,--privileged— not implemented onwslc run.--formatoninspect— no Go templates;list,imagesandstatsdo have--format json|table.
Verified against wslc 2.9.4.0 by dumping --help for all 43
command paths and executing each flag on a Windows Server 2025 runner. Both the flag table and
this list come from that output, not from documentation.
Hit an error that is not obviously one of these? The error diagnostic matches your output against these limitations and tells you which one you are looking at.
FAQ
- What is the wslc equivalent of docker ps?
- wslc container list, or wslc list. Both ls and ps are registered aliases of wslc list on wslc 2.9.4.0, so wslc ps works too. Add --all to include stopped containers.
- What is the wslc equivalent of docker images?
- wslc image list, or the top-level wslc images. Both work. There is no wslc image history and no wslc image search in 2.9.4.0 — the image noun has build, remove, inspect, list, load, import, prune, pull, push, save and tag.
- How do I pass a GPU to a wslc container?
- Use --gpus, the same flag as Docker: wslc run --rm --gpus all nvidia/cuda:12.4-base nvidia-smi. Docker’s --device flag is not implemented on wslc 2.9.4.0 and is rejected as an unrecognized argument.