WSL2 Docker Quickstart: Running Docker on Windows via the Linux Subsystem

What the wsl2-docker-quickstart Guide Covers

The wsl2-docker-quickstart repository from codeedu is a written guide, not a software package. It explains how to install and configure WSL2 on Windows 10 or Windows 11, then run Docker containers inside that Linux environment. The guide is written in Portuguese, with an English translation available at README.en.md in the same repository. The audience is Windows developers who want to work with Docker containers using a real Linux kernel rather than a compatibility layer. The guide organizes its material into four major topics: WSL itself, WSLg for graphical applications, Docker installation, and a collection of tips and frequently asked questions. It covers enough ground to get a developer from a fresh Windows install to a working Docker environment.

From WSL1 to WSL2: Full Linux Kernel Support

Microsoft introduced the Windows Subsystem for Linux in 2016. The first version translated Linux system calls into Windows equivalents, which meant certain tools that relied on specific kernel behaviors could not run. Docker is one example: it depends on Linux namespaces and cgroups that WSL1 could not provide. WSL2, announced in 2019 and officially released on 28 May 2020, replaced the translation layer with a real Linux kernel running inside a lightweight Hyper-V virtual machine. The README describes three specific improvements in WSL2 over WSL1: execution of a complete Linux kernel, better filesystem performance for files inside the Linux environment, and full system call compatibility. This compatibility is what makes running Docker Engine natively inside WSL2 possible. Both WSL1 and WSL2 remain available, and a distribution can be converted between versions after installation.

Four Docker Modes on Windows: Two Are Obsolete

The guide identifies four approaches to running Docker on Windows. Docker Toolbox and Docker Desktop with Hyper-V are marked as obsolete in the guide's table of contents. The two current approaches are Docker Desktop with the WSL2 backend, and Docker Engine installed directly inside WSL2 without Docker Desktop at all. Docker Desktop with WSL2 gives a graphical interface, automatic startup integration, and official support from Docker Inc. The guide lists both advantages and disadvantages for this mode, including the fact that Docker Desktop has commercial licensing requirements for certain business uses. The native Docker Engine path installs Docker directly inside a WSL2 Ubuntu distribution, operates without any graphical layer, starts the daemon on demand or via systemd, and avoids the Docker Desktop dependency entirely. The choice between these two paths is the central practical decision the guide addresses.

Guide Structure: WSL Setup, WSLg, Docker Installation, and Tips

The guide is structured as a progression. The WSL section covers minimum requirements (Windows 10 Home or Professional, version 2004 or later), the step-by-step WSL2 installation process including upgrading from WSL1, integration with Windows Terminal, and Systemd support inside the subsystem. The WSLg section explains how to run graphical Linux applications on Windows 11, which added a display server infrastructure to WSL. The Docker section walks through installing either Docker Desktop or Docker Engine, with separate sub-sections for activating Docker in a specific Linux distribution, optimizing Docker Desktop resource limits, and enabling the autoMemoryReclaim feature. The tips section at the end covers practical concerns that frequently trip up newcomers: performance when working across Windows and Linux filesystems, accessing Windows drives from within WSL2, network behavior under LAN and VPN configurations, and how to enable BuildKit for faster Docker image builds.

Performance Constraints and Memory Configuration Files

One of the guide's more technical sections addresses how WSL2 uses machine resources and how to control that usage. WSL2 runs inside a virtual machine, so it maintains a virtual hard disk image on the Windows filesystem. The guide covers compacting and expanding this virtual disk, which can grow large over time without automatic reclamation. Memory behavior is configurable through two files: .wslconfig, which lives in the Windows user profile directory and controls settings for all WSL2 distributions on the machine, and wsl.conf, which lives inside each Linux distribution and controls per-distribution behavior. The guide also covers the autoMemoryReclaim setting, which instructs WSL2 to return unused memory to the host operating system. Without this setting, the WSL2 virtual machine can appear to hold onto memory even when Linux processes have freed it. Networking under VPN connections is another documented limitation: some VPN clients interfere with WSL2 network routing in ways that require workarounds specific to each VPN product.

Maintenance Status, Language, and What This Guide Leaves Out

The repository has no software license file listed in its metadata, which is worth noting if your organization has policies about using unlicensed content. The guide does not address Docker Compose orchestration in detail beyond its inclusion in Docker Desktop, does not cover Kubernetes inside WSL2, and does not document rollback procedures if a WSL2 upgrade causes problems. The guide is also narrowly focused on Windows: developers on macOS or Linux do not have a WSL2 layer and would use Docker Desktop or Docker Engine directly on their native systems. An alternative to this guide for getting Docker running on Windows is the official Docker Desktop documentation, which covers the same Docker Desktop path with vendor-maintained instructions. The wsl2-docker-quickstart guide's advantage over official docs is the side-by-side comparison with native Docker Engine and the tips section covering real-world edge cases. The last push to the repository was on 2026-03-28.

Editorial conclusion

Windows developers who spend most of their time running Linux-based containers will find the guide most useful for its side-by-side comparison of Docker Desktop and native Docker Engine. Developers who need a simple setup with a GUI should go with Docker Desktop and the WSL2 backend. Those who want to avoid Docker Desktop's resource overhead can follow the Docker Engine section instead. The guide does not cover production deployment or Kubernetes on WSL2, and the README does not document rollback procedures. The last push to the repository was on 2026-03-28.

Frequently asked questions

Official sources

1. codeedu/wsl2-docker-quickstart on GitHub
2. Issues
3. README