WSL Containers CLI: Qualify wslc for a Windows Container Workflow

Microsoft now documents a built-in WSL container command named wslc.exe. It can build, run, and interact with Linux containers, while the related WSL container API supports Windows applications that need a programmatic container lifecycle. Those are separate surfaces: this article focuses on evaluating the CLI, not replacing a general Docker or Podman deployment design.

Microsoft Learn currently documents WSL version 2.9.3 or higher as the minimum. Microsoft’s WSL 3.0.1 release, published September 29, 2026, marks WSL containers generally available and removes the preview designation. Use the current WSL release and installed help output rather than copying older preview instructions. General availability does not make the CLI a complete Docker CLI, Compose, Kubernetes, or production-orchestration replacement.

Confirm availability before writing automation

On Windows, capture the WSL version and ask the CLI for its own version:

wsl.exe --version
wslc.exe version
wslc.exe --help

Microsoft’s current tutorial uses wsl –update to install or update WSL. A platform update can affect every distro, so schedule it through the normal change process and preserve a recovery path. Confirm wsl.exe –version meets the documented minimum and that wslc.exe is available; if not, report the feature as unavailable rather than assuming a PATH or Linux package issue.

WSL containers use a WSL-managed session and host integration. The feature is not described as a container daemon installed inside the user’s Ubuntu distro. Do not conflate the user’s existing Docker Desktop integration, a systemd-managed Podman service, and the built-in wslc environment. Run wslc from the Windows side exactly as the official guide documents; do not assume a Linux shell can call a same-named binary or that an existing engine socket is shared.

Start with a disposable smoke test

The official tutorial provides a basic pull-and-run check:

wslc.exe run --rm hello-world

The expected result is a short successful container output; the first invocation may need to retrieve the image from its registry. A passing smoke test verifies a narrow path: the CLI can start a simple image on that host. It does not prove that private registry authentication, persistent volumes, port publishing, resource limits, GPU access, or a development workflow works.

Keep image sources explicit. Use a pinned tag or immutable digest for repeatable tests when the registry supports it; a mutable latest tag can change between trials. Record registry, image reference, architecture, WSL version, and host Windows build. On Windows Arm devices, confirm that image architecture and emulation path match the workload; the CLI’s presence does not guarantee every image has a native manifest for that processor.

Exercise the basic lifecycle

Microsoft’s WSL container page shows a pattern for running a web server, listing it, checking the published port, and stopping the container. A bounded test can use:

wslc.exe run --rm -d -p 8080:80 --name wslc-web nginx
wslc.exe container ps
curl.exe --fail http://localhost:8080/
wslc.exe container stop wslc-web

This illustrates documented commands, not a claim that every WSL network mode, firewall rule, or host policy permits the same route. Test the exact listener expected by the application, inspect the command’s exit code, and stop the container even when the HTTP check fails. Use a port that is available and bind narrowly where the CLI supports it. Do not expose a test server on a LAN address unless the test explicitly requires and authorizes that reachability.

After stop, confirm it is no longer running and that a later launch behaves according to the chosen persistence options. Distinguish removal of a container from removal of its image or data volume. Do not assume that a container’s writable layer is durable storage for application data. For stateful tests, use a disposable named volume and verify exactly where the feature stores its session data before depending on it.

Test image, build, and storage paths separately

If the workload builds an image, begin with a tiny Dockerfile and context. Confirm syntax against installed CLI help because commands and flags can evolve between WSL releases. Then test a larger representative context and record build duration, cache behavior, image size, and failure logs. A successful image build does not test registry push permissions, multi-platform output, Compose files, build secrets, or CI integration.

For a registry workflow, test pull, tag, and push with a disposable repository or image name. Use approved credentials and avoid putting passwords in command-line arguments or saved logs. The public tutorial’s simple image examples do not make every credential provider or registry policy compatible with the CLI. If a corporate proxy or private certificate authority is involved, evaluate that as its own network prerequisite.

For volumes and bind mounts, write, read, rename, and delete a disposable file from inside the container, then verify the host-side result. Test UID/GID behavior with the actual container user and a minimal file. Confirm whether the path is on the Linux filesystem or a Windows-backed share, because filesystem behavior and performance may differ. Do not infer durability from a container-style flag; verify what the WSL container docs currently support.

Define a compatibility boundary

Treat wslc as its own runtime interface, not as an alias for Docker Desktop. Before migrating a script, compare every command and option it relies on: build context, cache, environment variables, mount syntax, networks, port publishing, logs, resource limits, stop signals, image import/export, and exit-code behavior. A shared prefix such as run or image ls can improve familiarity without implying a complete API-compatible implementation.

Do not write a production playbook that depends on an undocumented command. Store the exact output of wslc –help and wslc <subcommand> –help with the WSL version used for qualification. Recheck after updates because CLI behavior can evolve. If automation needs an option not present in installed help, stop and use an engine whose documented interface supports that requirement rather than silently approximating its behavior.

The feature has a separate Windows application API as well as the CLI. If a Windows program needs to start containers and stream process output, use the official API surface rather than parsing CLI text or launching shell commands as an implicit protocol. The two approaches have different lifecycle and error handling.

Acceptance tests for a pilot

An engineering qualification should include:

Confirm a compatible WSL version, current release channel, and wslc version.
Run the official hello-world smoke test.
Run a pinned test image with a health check and deterministic exit status.
Verify port publication from the intended Windows client and network scope.
Exercise an ephemeral container and a named-volume persistence test.
Capture image pull/build logs, runtime version, and resource use.
Stop all test containers and verify no background process or test listener remains.

Repeat the test after a clean WSL shutdown, Windows restart, and WSL package update. Test both a cold image pull and a warm cached run. Compare with the engine the team currently supports using the same image, host load, and workload. Record operational friction, missing flags, logs, and performance; do not declare a winner based on the easiest hello-world run.

Decide where it belongs

The generally available feature can be useful for running Linux containers through WSL without installing a separate per-distro engine. Its GA status does not settle a team’s image policy, monitoring, backup, service uptime, GPU requirements, or deployment design. Keep developer convenience and service delivery as distinct requirements.

Adopt it only when the installed version, required commands, volume semantics, and update policy have all passed the project’s acceptance tests. For workloads requiring a support contract, service-level guarantees, or always-on operation, select an environment whose current support terms and lifecycle meet those requirements.

Conclusion

The built-in wslc CLI is a generally available WSL container surface, not proof that every existing Docker workflow transfers unchanged. Confirm version, test lifecycle and persistent data paths, record exactly which flags work, and requalify after updates. That yields useful evidence without assuming compatibility the current interface does not document.

Related:

Sources: