microsoft/WSL: what the repository actually contains, and how to install WSL on Windows 10 or 11

Who the microsoft/WSL repository is for

The README describes WSL as a way to run Linux command-line tools, utilities and applications unmodified and directly on Windows, without the overhead of a traditional virtual machine or dual boot. That sentence defines the audience: developers who want apt, gcc, Python or a shell on a Windows laptop and do not want to reboot or manage a VM image.

The repository itself is not aimed at those end users. It is the source for the WSL stack: the top-level entries include CMakeLists.txt, src/, cmake/, distributions/, msixinstaller/, msixgluepackage/, msipackage/, test/ and tools/. This is a C++ project with a CMake build, packaged as MSIX and MSI artifacts. The README points users at the documentation site and the releases page, and points contributors at CONTRIBUTING.md and doc/docs/dev-loop.md for building from source.

So there are two distinct readers. One installs WSL with a single command and never opens this repository. The other wants to build the stack, file a bug with a reproduction, or read how distributions are registered. The README is explicit that contributions of all types are welcome, including documentation fixes and design proposals, which is a signal that the project expects outsiders to read the tree rather than only the release notes.

How WSL2 is put together in this tree

The name of the repository is slightly misleading. WSL is not one binary. The README links three related repositories: microsoft/WSL2-Linux-Kernel for the Linux kernel shipped with WSL, microsoft/WSLg for Linux GUI app support, and microsoftdocs/wsl for the documentation. Those are separate codebases, and the kernel in particular is maintained outside this tree.

Inside this repository, the layout tells you where things live. src/ holds the implementation, cmake/ and CMakeLists.txt drive the build, distributions/ relates to the Linux distributions that can be registered, and the msixinstaller/, msixgluepackage/ and msipackage/ directories are the packaging layers that put the result on a Windows machine. test/ and cloudtest/ are the test surfaces, and diagnostics/ and triage/ exist for support work.

The practical consequence is that a WSL install is a Windows-side component plus a separately versioned Linux kernel plus a distribution root filesystem. Updating the Windows component does not necessarily update the kernel, and it does not touch your Ubuntu userland. That separation is why the project can ship frequent point releases while your files inside the distribution stay put.

How to install WSL on Windows 10 and Windows 11

The README gives one command, run inside a Windows command line. It installs WSL and, on a machine where no distribution is present, prompts for one.

wsl --install

After it completes and the machine restarts if prompted, a new Linux distribution is registered and you are asked for a UNIX username and password. From then on, typing wsl at a Windows prompt drops you into that distribution's shell.

The README directs readers to the releases page for downloads and release notes, and to the setup best practices page in the documentation. For machines where the inbox component is old, the releases page is the place the project points to for a newer build; the README does not document a rollback procedure if an update misbehaves, so treat that as an open question before you upgrade a working machine.

To check what you have after installing, wsl --status reports the default distribution and the default WSL version. If you want a second distribution alongside the first, the documentation covers distribution management; the README itself does not enumerate the available distributions, only the distributions/ directory in the source tree hints that they are a first-class concept.

Where WSL is the wrong tool

The README's own framing is the limitation. WSL is for Linux command-line tools and applications, not for replacing a Linux server or a Linux desktop. If your workload needs a display manager, a custom kernel module, or systemd units that assume a real boot sequence, WSL is not the environment you are looking for.

There is a second boundary that the README states plainly: WSL exists to avoid the overhead of a traditional virtual machine. That is a design goal, not a guarantee of identical behaviour. Questions people ask, such as whether WSL is as good as native Linux, are not answered in this repository's README at all. The README does not publish a compatibility matrix, and it does not claim parity with a bare-metal Linux install. If your acceptance criteria include syscall-level fidelity or kernel-version-specific behaviour, you need to test that yourself rather than assume it.

A third boundary is telemetry. The README's privacy section states that the application logs basic diagnostic data and may send information about you and your use of the software to Microsoft, and that you may turn off telemetry as described in the repository. DATA_AND_PRIVACY.md is the file to read. In a regulated environment, that is a decision point, not a footnote.

The alternative: a full virtual machine or a dual boot

The README names the alternative in its first paragraph: a traditional virtual machine or a dual boot setup. The difference is architectural. A VM gives you a complete guest with its own kernel boot, its own display stack and its own device model, at the cost of memory and disk for the guest plus a hypervisor layer. WSL2 also uses virtualization under the hood, but the README presents it as avoiding the overhead of a traditional VM, and the integration surface (Windows-side packaging, distribution registration, the WSLg repository for GUI apps) is specific to this stack.

A dual boot is the other end: full native performance and full hardware access, paid for with a reboot every time you switch. If your work is mostly Windows with occasional Linux tooling, WSL is the lighter option. If your work is mostly Linux with occasional Windows, dual boot or a dedicated Linux machine is the more honest setup, and no amount of WSL configuration changes that.

For GUI applications specifically, the README points to microsoft/WSLg rather than claiming that support lives in this repository. That is a useful signal about where to file issues.

Licence, releases and what maintenance costs you

The repository is MIT licensed, with LICENSE and NOTICE.txt at the top level. MIT is permissive: you can use, modify and redistribute the code, including in commercial products, provided the copyright notice and permission notice are preserved. That is the general shape of the licence, not legal advice; if you are redistributing WSL components inside a product, read LICENSE and NOTICE.txt and the trademark section of the README, which states that authorized use of Microsoft trademarks must follow Microsoft's Trademark and Brand Guidelines.

The release cadence visible in the repository is fast. 2.7.12 was published on 2026-08-18, 2.9.8 on 2026-08-24, and 2.9.9 on 2026-08-25. The last push to master was on 2026-08-25, which is within the last month, so the project is actively developed. That cadence is the maintenance cost: if you pin to a specific build, you own the decision to stay behind, and the README does not describe a long-term support track or a rollback path.

For contributors rather than users, the cost is different. The README asks you to read CONTRIBUTING.md before starting work and points to doc/docs/dev-loop.md for build instructions and architecture details. A CMake-based C++ project of this size is not a casual first contribution, and the presence of a Code of Conduct and a SECURITY.md suggests the project takes process seriously.

Editorial conclusion

Adopt microsoft/WSL if you want Linux command-line tools and GUI apps running on Windows without a dual boot, and you are willing to run wsl --install and then wsl --update to keep the stack current. Do not adopt it if you need a full Linux desktop session with its own display manager and kernel modules, or if you need a hypervisor-free environment. Before committing, verify on your own machine that wsl --install completes and that wsl --status reports the WSL2 default version, and check the release notes for the build you land on.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes