How to install WSL containers on Windows 11

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

WSL containers is not a separate download. The runtime, the wslc.exe CLI and the container host all ship inside the Windows Subsystem for Linux, so installing it means moving WSL onto a pre-release channel and restarting the subsystem. The whole process is two commands and takes under ten minutes on a machine that already has WSL 2.

Prerequisites

Four things have to be true before wslc will appear on your machine. Check all of them first — every failure mode in the last section traces back to one of these.

If the last one reports Disabled, enable it and reboot:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Install WSL containers in two commands

Open PowerShell as Administrator and run:

# 1. Move WSL onto the pre-release channel and update
wsl --update --pre-release

# 2. Restart the subsystem so the new container host loads
wsl --shutdown

The update pulls a WSL build of 2.9.3.0 or newer, which is the first version that contains the container host. Expect a 150–250 MB download. The wsl --shutdown is not optional: until every existing distribution and the old service process are torn down, wslc will start and then immediately fail to reach its host.

Verify the install

wsl --version          # expect 2.9.3.0 or newer
wslc version           # CLI + runtime versions
wslc info              # storage driver, VM state, resource limits

wslc info is the useful one. It starts the utility VM on demand, so a clean response proves the whole chain works: CLI → host service → Hyper-V VM → image store. If wslc version answers but wslc info hangs, the VM is failing to boot and the fix is almost always virtualisation or a conflicting hypervisor (see below).

Run your first container

# smallest possible smoke test
wslc run --rm alpine echo "wslc works"

# pull, run detached, publish a port
wslc pull nginx:alpine
wslc run -d -p 8080:80 --name web nginx:alpine

# confirm it is up, then check from Windows
wslc container list
curl.exe http://localhost:8080

# clean up
wslc stop web
wslc container remove web

Note wslc container list rather than docker ps. wslc groups listing commands under nouns; recent previews accept wslc ps as an alias but the noun form is the stable one. The command converter handles this translation for whole scripts at once.

The curl.exe http://localhost:8080 check matters more than it looks. wslc routes container traffic through the Windows host network stack, so a published port is reachable on localhost from Windows itself with no extra port-proxy step — and it inherits your corporate VPN, firewall rules and proxy settings automatically. If this call fails while wslc container list shows the container running, you have a Windows Firewall rule problem, not a container problem.

Wire WSL containers into VS Code

The Dev Containers extension talks to Docker by default, but it only needs a CLI that speaks the same verbs. Point it at wslc:

// settings.json
{
  "dev.containers.dockerPath": "wslc"
}

Rebuild the container after changing this. Most single-container devcontainer.json files work unchanged. Anything using dockerComposeFile will not — there is no Compose runtime in wslc, which is covered in the Compose migration guide.

Five errors that block most first runs

'wslc' is not recognized as an internal or external command

The binary was never laid down. Run wsl --version; anything below 2.9.3.0 means the --pre-release update did not apply. The usual cause is the in-box WSL component being active instead of the Store build — install WSL from the Microsoft Store, then repeat wsl --update --pre-release. A new terminal is also required, since PATH is only read at shell start.

The Virtual Machine Platform feature is not enabled

Run the dism.exe command from the prerequisites section and reboot. On machines managed by enterprise policy this feature is sometimes blocked by Group Policy, in which case the DISM call succeeds but the feature reverts after restart — check with your IT team rather than fighting it locally.

Utility VM fails to start / wslc info hangs

Something else owns the hypervisor. VirtualBox below 7.0, VMware Workstation below 17, and some Android emulators and anti-cheat drivers take exclusive control of virtualisation extensions. Check the state of Hyper-V's own boot setting:

bcdedit /enum | findstr -i hypervisorlaunchtype

If it reports Off, re-enable it with bcdedit /set hypervisorlaunchtype auto and reboot. Note that this will slow down or break older VirtualBox/VMware installs — that trade-off is inherent to running any Hyper-V-based container runtime, wslc included.

failed to resolve registry on the first pull

DNS inside the utility VM is not resolving. Because wslc inherits the host network configuration, this usually means a VPN client is intercepting DNS. Reconnecting the VPN after wsl --shutdown fixes most cases, since the VM picks up the current host resolver at boot rather than watching for changes.

Permission denied on a bind-mounted Windows directory

Host directories are shared over VirtioFS, which maps Windows ACLs onto Linux UIDs approximately. A container process running as a non-root user often cannot write to a mounted Windows path. Two workarounds: run the container as root for local development, or keep write-heavy working directories inside a wslc-managed volume and mount the Windows path read-only.

# read-only host mount, writable named volume for output
wslc volume create build-out
wslc run --rm -v C:/src/myapp:/app:ro -v build-out:/app/dist myapp:dev

Use forward slashes in Windows paths. Backslashes are interpreted as escape characters by the argument parser and produce confusing "no such file or directory" errors.

How to roll back

The pre-release channel is sticky — later wsl --update calls stay on pre-release until you tell them otherwise. To return to the stable channel:

wsl --update            # stable channel
wsl --shutdown

This removes wslc and its container host. Images and named volumes stored in the wslc image store are left on disk and will be picked up again if you re-enable the preview later, so a rollback is not destructive. Your Linux distributions and their filesystems are untouched throughout — the container host is a separate VM.

FAQ

How do I install WSL containers on Windows 11?

Run `wsl --update --pre-release` in an elevated PowerShell window, then `wsl --shutdown` to restart the subsystem. Verify with `wslc version`. WSL containers ships inside WSL itself, so there is no separate download or installer.

What Windows version do I need for WSL containers?

Windows 11 22H2 or later on x64 or ARM64, with virtualisation enabled in firmware and the Virtual Machine Platform optional feature turned on. Windows 10 is not supported because the container host relies on a newer Hyper-V utility VM path.

Why does wslc say it is not recognised as a command?

The wslc.exe binary is only laid down by pre-release WSL builds. Confirm with `wsl --version` that the WSL version is 2.9.3.0 or newer; if it is lower, the `--pre-release` flag did not take effect, usually because the Microsoft Store version of WSL was not the active one.

Do I have to uninstall Docker Desktop first?

No. wslc and Docker Desktop can coexist because wslc uses its own utility VM and its own image store. They do not share images, so anything you already pulled with Docker must be pulled again.

Related guides