wslcontainers
Public preview · Windows 11

Docker → wslc command converter

WSL containers run Linux containers natively on Windows 11 — no Docker Desktop, no daemon, no licence. Paste a Docker command below to get the wslc equivalent, plus the flags that quietly behave differently.

Try an example

# Paste a docker command above
Runs locally in your browser. Nothing is uploaded.

On this page

  1. Full Docker to wslc command mapping
  2. Installing WSL containers
  3. How it compares to Docker Desktop
  4. Migrating a Compose stack
  5. VS Code dev containers with wslc
  6. Why Testcontainers cannot attach
  7. Frequently asked questions

Full Docker to wslc command mapping

7 verbs are byte-for-byte identical, 6 are grouped under a noun, 7 exist with behavioural differences, and 7 have no equivalent in the current preview. That last group is where migrations actually break, so check it first.

DockerwslcStatusNotes
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.

Free tools

Compose migration analyser →

Paste a docker-compose.yml and see which fields map cleanly, which need changing, and which have no wslc equivalent. Exports a startup script for the whole stack.

Error diagnostic →

Paste a failing command's output to find the specific wslc limitation behind it, with fix steps grounded on documented failure modes rather than generic Docker advice.

Start here

Install WSL containers →

Enable the preview, verify wslc works, and fix the four errors that block most first runs.

wslc vs Docker Desktop →

Feature-by-feature comparison, plus an honest list of what you give up by switching.

Migrating from Compose →

wslc has no Compose runtime. Here is how to translate a compose file field by field.

VS Code dev containers →

One setting points the Dev Containers extension at wslc. What works, what breaks.

Testcontainers & wslc →

It cannot attach — wslc exposes no Docker socket. The supported workaround.

Docker ↔ wslc cheat sheet →

Every command, flag and path convention side by side on one printable page.

Frequently asked questions

What are WSL containers?
WSL containers is a feature of the Windows Subsystem for Linux that runs OCI-compatible Linux containers natively on Windows 11 without Docker Desktop or Podman. Containers run daemonless as processes inside a dedicated Hyper-V utility VM, driven by a built-in CLI called wslc.exe (also aliased to container.exe).
Is wslc a drop-in replacement for the Docker CLI?
Mostly. run, build, pull, push, exec, logs and stop take the same flags. Listing commands moved to noun form — wslc container list rather than docker ps. Compose, Swarm, buildx bake and restart policies have no equivalent yet.
Do I still need Docker Desktop?
No, for everyday build-and-run work. WSL containers ships with WSL itself, so there is no third-party runtime and no Docker Desktop subscription. Keep Docker around only for Compose stacks, Swarm, or multi-platform buildx builds.
Is it faster than Docker Desktop?
For host file access, yes — wslc shares directories over VirtioFS, which Microsoft measures at up to twice the throughput of the older sharing path. There is also no background daemon holding memory when nothing is running. Raw container CPU throughput is comparable, since both ultimately run Linux under Hyper-V.
Can containers use my GPU?
Yes, and the flag is the same one you already know: --gpus. On wslc 2.9.4.0 wslc run --help lists --gpus with the description “Add GPU devices to the container (‘all’ to pass all GPUs)”. Docker’s --device is not implemented — passing it fails with Argument name was not recognized for the current command: '--device'. On a host with no GPU, --gpus all is accepted but the container fails to start with an ldconfig failed with status 0x100 hook error.
Is this production ready?
Not yet. It is a public preview shipped behind wsl --update --pre-release, and the command surface still changes between releases. It is solid for local development; do not build CI pipelines on it until it reaches general availability.