WSLC containers

Everyday wslc.exe is Microsoft's command-line tool for running Linux containers on Windows, and it ships with WSL.

Source of truth

Docs: WSL container · Settings
Tested with: WSLC 3.0.3 on Windows 11. Commands were run on this version, except wslc settings and wslc settings reset, which come from Microsoft's docs.

Install

It's built in, and needs WSL 2.9.3 or newer.

wsl --update
wslc --version

Open a new terminal if wslc isn't found right after updating.

First container

wslc run --rm alpine echo hello

Images come from Docker Hub by default, so alpine resolves to docker.io/library/alpine:latest.

Run a web server

wslc run -d --name web -p 8080:80 nginx:alpine
curl.exe http://localhost:8080
wslc logs web
wslc exec web nginx -v
wslc stop web
wslc remove web

Ports bind to 127.0.0.1 by default, so only your own machine can reach them.

Everyday commands

The flags will look familiar if you've used Docker.

Command	What it does
wslc run IMAGE	Create and start a container
wslc list	List containers
wslc images	List images
wslc pull IMAGE	Download an image
wslc logs NAME	Show a container's output
wslc exec NAME CMD	Run a command in a running container
wslc stop NAME	Stop a container
wslc remove NAME	Delete a container
wslc rmi IMAGE	Delete an image
wslc info	Show versions, sessions and the settings file path

Useful run flags:

Flag	What it does
--rm	Delete the container when it stops
-d	Run in the background
--name NAME	Give it a name
-p 8080:80	Publish a port as host:container
-e KEY=value	Set an environment variable
-v HOST:CONTAINER	Mount a folder or volume
-w /app	Set the working directory
-m 512M, --cpus 1	Limit memory and CPU

-m may print a warning about swap limits. In testing, the container still ran normally.

Use a project folder

wslc run --rm -v "${PWD}:/app" -w /app alpine ls

The container can change anything in that folder, so mount only what it needs.

Build an image

# Dockerfile
FROM alpine
CMD ["echo", "built-with-wslc"]

wslc build -t my-image .
wslc run --rm my-image

Keep data with volumes

wslc volume create my-data
wslc run --rm -v my-data:/data alpine sh -c "echo saved > /data/file"
wslc run --rm -v my-data:/data alpine cat /data/file
wslc volume remove my-data

Sessions

Containers run inside a session, a lightweight WSL-backed VM. It starts on your first command and shuts down after 30 idle seconds by default.

wslc system session list
wslc system session terminate

Stopping a session is how you apply changed session.* settings. In one test on a fast desktop, a run took about 350 ms with the session already up and about 2.8 s from a stopped one. Raise idleTimeout if the cold starts annoy you.

Settings

Create and open the file at %LOCALAPPDATA%\wslc\settings.yaml:

wslc settings

session:
  cpuCount: 4
  memorySize: 8GB
  maxStorageSize: 500GB
  storagePath: D:\data
  defaultBindingAddress: 127.0.0.1
  idleTimeout: 60

Setting	Default	Notes
session.cpuCount	All logical processors
session.memorySize	50% of Windows memory
session.maxStorageSize	1TB	Limit for the disk holding images and containers
session.storagePath	%LOCALAPPDATA%	Changing it doesn't move existing data; you get a new, empty session
session.defaultBindingAddress	127.0.0.1	0.0.0.0 exposes published ports to your network
session.hostLoopback	host.wslc.internal	Name containers use to reach Windows. none disables it
session.idleTimeout	30	Seconds before an idle session shuts down
credentialStore	wincred	Where wslc login saves credentials. The other option is file

.wslconfig doesn't apply to containers. To restore the defaults, run wslc settings reset.

What's missing

• Compose: wslc compose isn't a command in 3.0.3. The request is tracked on GitHub, so check there for progress. Community wrappers exist, but they aren't Microsoft's, so read their code first.
• GUI: it's command line only.

WSLC or Docker?

Use	When
WSLC	Single containers and builds, with nothing extra to install
Docker	compose.yaml, a GUI, or tools that expect a Docker daemon

Claims that WSLC is faster than Docker Desktop are mostly unverified, so time your own workload before switching. The real choice today is usually whether you need Compose.

Security

• Registry credentials: saved in Windows Credential Manager by default.
• Public images: treat them like any other code you download. Prefer official images and pinned tags.
• Reaching Windows: containers can reach the Windows host through host.wslc.internal. Set hostLoopback to none if you don't need that.
• Mounts: a container can change whatever you mount, so never mount your whole user folder.

Related

• WSL setup & distros
• Docker & hosting
• WordPress local (Docker / DDEV)