Do I need to uninstall Docker Desktop to use wslc?

No. They can coexist because wslc runs in its own Hyper-V utility VM with its own image store. The trade-off is that images pulled with Docker are not shared with wslc — you pull them again.

Can wslc run docker-compose files?

Not directly. The wslc public preview has no Compose runtime and no wslc compose subcommand. Each service must be translated into a wslc run command, or driven from a script. See the Compose migration guide for a field-by-field translation.

How does wslc differ from Docker?

The CLI mirrors Docker for core verbs (run, pull, build, exec, logs, stop). Listing commands use noun form (wslc container list instead of docker ps). Restart policies are not yet supported, and there is no Compose/Swarm/orchestration layer. The runtime uses Moby under the hood, same engine as Docker.

Is WSL containers production ready?

It is a public preview (version 2.9.4.0 in mid-2026), with Microsoft targeting general availability in autumn 2026. It is stable for local development, testing, and CI/CD pipelines. For production workloads, wait for GA or test thoroughly against your specific stack.

Can containers use my GPU?

Yes. wslc supports GPU passthrough via the --gpus flag, the same as Docker. The container accesses the Windows GPU driver through CDI (Container Device Interface) specs. GPU support is maturing, so some frameworks may need additional configuration.

WSL Containers Complete Guide

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

WSL containers is Microsoft's answer to Docker Desktop on Windows. It brings native Linux container support directly into the Windows Subsystem for Linux, without requiring a third-party runtime, subscription, or Docker license. This guide covers everything from installation to advanced usage, with practical examples and migration paths.

## What are WSL containers? WSL containers is a feature of the Windows Subsystem for Linux that provides: - **`wslc.exe` CLI** — a Docker-compatible command-line tool for building, running, and managing containers - **WSL Container API** — a native API (C#, C++, C) for Windows applications to programmatically control Linux containers Rather than running containers inside a shared VM like Docker Desktop, wslc creates a dedicated Hyper-V utility VM per session, providing stronger isolation and cleaner integration with Windows.

Why this matters
For developers and IT teams on Windows, WSL containers eliminates the need for Docker Desktop licensing and provides a more native, integrated container experience. It is especially valuable for enterprises that want to standardize on Microsoft's ecosystem without sacrificing Linux container workflows.

## Quick Start: Get Running in 5 Minutes Get up and running with WSL containers. This is the fastest path from zero to your first container.

If you see "Hello from WSL containers!", you're running Linux containers natively on Windows with no Docker Desktop. ## Core Features ### Docker-Compatible CLI The wslc CLI mirrors Docker's command structure for familiar operations. If you know Docker, you already know wslc.

### Custom Image Builds wslc uses standard Containerfile/Dockerfile syntax, making it easy to migrate existing build pipelines.

### Key Characteristics | Capability | Description | |-|----| | **Isolation** | Each session gets its own Hyper-V utility VM, separate from other sessions | | **Performance** | Direct VirtioFS file sharing; measured up to twice the throughput of the older 9p path | | **Daemonless** | No long-running dockerd; the CLI starts the utility VM on demand, near-zero idle memory | | **GPU** | `--gpus all` passes the Windows GPU via CDI specs, same flag as Docker | ## WSL containers vs Docker Desktop: Key Differences Understanding where wslc excels and where it is still catching up is crucial for adoption decisions.

Current Limitations
As a public preview, WSL containers has important gaps: No Compose runtime, no built-in service discovery between containers, and GPU support is still stabilizing. For greenfield projects and local development it is excellent. For complex multi-service setups, you will need to orchestrate manually or wait for Compose support.

## Migrating from Docker Compose One of the most common questions: "Can I use my docker-compose.yml?" The answer is not yet, but migration is manageable.

For a detailed field-by-field translation, see the [Compose migration guide](/guides/compose/). ## Use Cases & Examples ### Development Environment Run your entire dev stack — database, cache, API — with wslc instead of Docker. ### CI/CD Pipelines Use wslc on GitHub Actions windows-2025 runners for Windows-native container testing. The [CI/CD guide](/guides/cicd/) covers the tested workflow. ### AI/ML Workloads Run PyTorch, TensorFlow, and other AI frameworks with GPU access via wslc's `--gpus` flag. ## Troubleshooting Common Issues ### "wslc is not recognized" Ensure you're running pre-release WSL: `wsl --update --pre-release`, then restart WSL with `wsl --shutdown`. ### GPU not working GPU support requires specific Windows driver versions and the `--gpus` flag. Verify with `wslc run --rm --gpus all nvidia/cuda:12.4-base nvidia-smi`. The `--device` flag does not exist on wslc — it is rejected as an unrecognized argument. ### Network connectivity issues Containers use the host's network stack by default. For isolated networks, use wslc's network subcommands (`wslc network create`), a preview feature. For more solutions, try our [error diagnostic tool](/tools/diagnose/). ## Production Readiness Assessment **Current status: Public Preview (v2.9.4.0)** | Aspect | Status | Recommendation | |-|----|----| | Local development | Stable | Recommended | | CI/CD testing | Works on windows-2025 | Use with care | | Production workloads | Preview only | Wait for GA | | Enterprise security | Intune + MDE | Viable | | GPU-intensive apps | Maturing | Test thoroughly | **Microsoft targets General Availability in autumn 2026.** For teams wanting to be early adopters, now is the time to evaluate non-critical workloads and provide feedback. ## What's Next - **Follow the [installation guide](/guides/install/)** for step-by-step setup - **Try our [Docker-to-wslc converter](/) for quick command translation** - **Browse the [tested images matrix](/images/)** to see what works on wslc - **Read the [cheat sheet](/reference/cheatsheet/) for daily command reference** - **Watch for GA announcement** — the timeline is autumn 2026 ## Go deeper on the known gaps - [wslc Compose support](/guides/wslc-compose/) — what exists, what is coming, how to migrate - [wslc on Windows Server](/guides/windows-server/) — 2025 supported, 2022 not - [GPU troubleshooting](/guides/gpu-troubleshooting/) — NVIDIA and AMD failure modes - [Pulling behind a proxy](/guides/registry-proxy/) — corporate, PAC, and China mirrors - [Docker-in-Docker](/guides/docker-in-docker/) — why it fails and workarounds - [Docker socket & DOCKER_HOST](/guides/docker-socket/) — what is missing - [Privileged & capabilities](/guides/privileged/) — FUSE/CVMFS blocked - [Feature tracker](/requirements/) — all 34 open wslc issues ## Frequently Asked Questions

Is WSL containers really free?

Yes. WSL containers is included with Windows, no extra cost. Unlike Docker Desktop, there is no subscription or licensing fee for commercial use.

Can I use my existing Docker images?

Images are not shared between Docker and wslc. You'll need to pull them again with `wslc pull`. However, image formats are compatible (OCI standard), so you can use the same registries.

Does Kubernetes work with WSL containers?

Kubernetes is not yet available for wslc. For orchestration, consider using wslc's container management commands or community scripts. Kubernetes support is on the roadmap but not yet announced.

What about Podman support?

WSL containers is a separate runtime. While Podman Desktop can manage WSL containers through its remote connection feature, the primary CLI is wslc.exe. The two tools can coexist but are independent.

WSL Containers Complete Guide

Related guides

Installation guide →

wslc vs Docker Desktop →

Compose migration →

Docker-to-wslc converter →