py

docker2wslc

Translate Docker commands, Compose files and dev container configs to wslc — the native Linux container runtime built into the Windows Subsystem for Linux, which runs containers on Windows 11 without Docker Desktop.

No network calls, no daemon, no telemetry. Pure rule-driven translation.

pip install docker2wslc          # translation only
pip install 'docker2wslc[yaml]'  # + Compose analysis

Convert a command

$ docker2wslc convert docker run --gpus all --restart always -p 8080:80 nginx
wslc run --gpus all -p 8080:80 nginx

Migration notes
  WARN  Restart policies are not implemented in the wslc preview. Flag dropped — use a
        Windows scheduled task or a wrapper script for auto-restart.
  INFO  `--gpus` is native in wslc 2.9.4, but the host must actually have the GPU: on a
        machine without one, `--gpus all` fails at container init with an ldconfig error.

Commands come from arguments, a file, or stdin:

docker2wslc convert docker ps -a
docker2wslc convert --file deploy.sh
cat deploy.sh | docker2wslc convert

Analyse a Compose file

wslc has no Compose runtime. This turns each service into an equivalent wslc run and tells you exactly what cannot be carried over:

$ docker2wslc compose docker-compose.yml
# wslc has no Compose runtime. Equivalent commands:

wslc volume create pgdata
wslc network create backend
# start order matters: web -> db

# service: web
wslc run -d --name web -e NGINX_HOST=localhost -p 8080:80 --network backend nginx:alpine
  ! networks: Bridge-only. Create with wslc network create before running.
  x depends_on: No dependency ordering. Start services in order yourself and add readiness waits.
  x restart: No restart policies in the wslc preview.

# service: db
wslc run -d --name db -v pgdata:/var/lib/postgresql/data --network backend --health-cmd 'pg_isready -U postgres' --health-interval 10s --health-retries 5 postgres:16-alpine
  ! volumes: Named volumes must be created first with wslc volume create. Windows paths go over VirtioFS.
  ! networks: Bridge-only. Create with wslc network create before running.

Lint a repository

Scans for docker-compose.y*ml, compose.y*ml and devcontainer.json:

docker2wslc lint .

Use in CI

Exit codes are meaningful, so this works as a gate:

Code	Meaning
0	Fully compatible
1	Degraded — flags dropped or rewritten, still runnable
2	Unmigratable — Compose, Swarm, buildx, or a parse failure

- run: pip install 'docker2wslc[yaml]'
- run: docker2wslc lint .        # fails the job on exit 2

Python API

from docker2wslc import translate, analyse

result = translate("docker run --platform linux/amd64 -it ubuntu bash")
print(result.output)      # wslc run -it ubuntu bash
print(result.exit_code)   # 1
for note in result.notes:
    print(note.severity, note.text)

report = analyse(open("docker-compose.yml").read())
print(report.as_dict())

--json on any subcommand gives the same structure for shell pipelines.

What wslc cannot do

Worth knowing before you migrate. These are runtime limitations, not gaps in this tool:

• No Compose runtime — translate services by hand, see the migration guide
• No restart policies — use a scheduled task
• No --platform — host architecture only
• No depends_on gating — health flags work (--health-cmd et al), but nothing waits on health state for you
• No Docker socket or Engine API — Testcontainers, Portainer and act cannot attach
• No buildx / bake — single-platform wslc build only
• GPU — --gpus all, the same flag as Docker. It is --device that wslc lacks.

CLI-driven tooling ports to wslc. API-driven tooling does not. That single distinction explains most migration surprises — including why VS Code Dev Containers does work once you set dev.containers.dockerPath to wslc.

Docs

• Interactive converter — https://wslcontainers.com
• Command cheat sheet — https://wslcontainers.com/reference/cheatsheet/
• Install guide — https://wslcontainers.com/guides/install/
• wslc vs Docker Desktop — https://wslcontainers.com/guides/vs-docker-desktop/

Accuracy

Rules target the 2026-07 wslc public preview and live in a single rules.json shared by the Python package, the npm CLI, the MCP server and the VS Code extension. wslc is a moving target; if you hit a mapping that is wrong, open an issue with the command and the actual wslc output.

MIT licensed.