MicrosoftDocs/WSL: the documentation repository behind Windows Subsystem for Linux

What MicrosoftDocs/WSL actually is, and who should clone it

The repository is documentation source, not software. Its README calls it "the markdown source for Microsoft's command-line shells and console documentation," and the rendered result lives at learn.microsoft.com/windows/wsl. Everything a reader sees on that page starts as a file in the WSL/ folder here.

That narrows the audience considerably. This repo is for people who write, correct, translate or review WSL documentation, and for engineers who want to see the source of a page before trusting the rendered version. It is not for someone who wants WSL running on a machine. If you are looking for WSL download or WSL Microsoft Store instructions, the README does not carry them; it links out to the rendered site and to the release notes page instead.

The README is explicit about the boundary: "this repo's issue tracker is only for reporting issues with the WSL docs." Runtime bugs go to Microsoft/WSL, and Windows Console bugs go to Microsoft/Terminal. Filing a kernel or networking bug here sends it to the wrong queue.

How the docset is laid out and published

The top level mixes content and publishing metadata. WSL/ holds the markdown. The .openpublishing.publish.config.json file describes the docset that the publishing system builds, and .openpublishing.redirection.json maps old URLs to new ones so links do not break when a page moves. LICENSE, LICENSE-CODE and ThirdPartyNotices sit alongside them, and .github/ carries the contribution plumbing.

The data flow is one direction: a contributor edits markdown in WSL/, a pull request merges, and the publishing configuration turns that tree into the site at learn.microsoft.com/windows/wsl. There is no build step a reader runs locally to see the final page. The redirection file is the part people forget. Rename a heading and the anchor changes; move a file and you need an entry there, or the old link dies silently.

The two licence files matter for a different reason. The README states the repository is "distributed under the Creative Commons Attribution 4.0 International (CC BY 4.0) Public License," while LICENSE-CODE exists separately. That split usually means prose and code samples are not covered by identical terms, and the README does not spell out which file governs which path. Read both before you reuse a snippet.

Cloning the docs repo and making a first edit

The README gives no install procedure, because there is nothing to install. The workflow is clone, edit, open a pull request, and the README states that pull requests in particular are welcome. The repository URL is the one printed in the README's issue section, and the documentation files live under the WSL/ folder listed among the top-level entries.

git clone https://github.com/MicrosoftDocs/WSL.git
cd WSL

You should end up with the repository contents, including the WSL/ folder that holds the markdown, the .openpublishing.publish.config.json docset file, and .openpublishing.redirection.json. Pick a file under WSL/, read it, and make a text change.

When you are ready to propose it, push a branch and open a pull request against the default branch, main. If your change renames or moves a page, check .openpublishing.redirection.json in the same commit. Nothing in the README documents a local preview command for the rendered site, so the pull request review is where the published result gets checked. If you only wanted to read the docs rather than change them, the rendered site linked from the README is the faster path.

Where this repository is the wrong tool

The most common mistake is treating MicrosoftDocs/WSL as the WSL project. It is not. Cloning it gives you markdown, not a Linux distribution, not a kernel, and not the wsl.exe command line. Nothing here installs a subsystem.

The second limitation is the issue tracker's scope. The README points runtime problems to Microsoft/WSL and console problems to Microsoft/Terminal. A documentation repository cannot reproduce a networking failure or a filesystem performance regression, and the maintainers of this repo are not the people who fix them.

The third is release history. The releases listed for this repository carry build-style tags such as 21354 and 21286, dated 2021, and the README points to a separate release notes page for WSL itself. Those tags do not describe the WSL runtime version you have installed. Reading them as a changelog for the product would be a misreading of what this repository tracks.

Finally, the README does not document rollback, a local preview environment, or a translation workflow. If your contribution depends on any of those, the repository is silent and you are working from the rendered site and the pull request review instead.

MicrosoftDocs/WSL compared with Microsoft/WSL

The real alternative is not another documentation tool. It is Microsoft/WSL, the runtime repository the README links to for issue reporting. The difference is what each one contains and who acts on it.

MicrosoftDocs/WSL holds prose: pages about installation, configuration, networking and interoperability, written in markdown and published through the Open Publishing configuration files at the repository root. A change here alters what a reader is told. Microsoft/WSL holds the subsystem itself, so a change there alters what the software does. If your problem is that a documented command does not behave as described, the documentation repository is the right place to report the discrepancy. If the command fails outright, it is not.

The same split applies to the console. The README names Microsoft/Terminal for Windows Console issues, which is a third repository with a third maintainer group. Three repositories, three queues, and the README is the only place in this material that states which one takes what.

Maintenance, licence and what a contributor inherits

The repository is not archived, and the last push was on 2026-09-28, so it is being touched. That tells you the documentation is current; it does not tell you how quickly a given pull request will be reviewed, and the README makes no promise about review time.

The upgrade cost for a consumer of this repository is close to zero, because there is no dependency to upgrade. You pull the branch and you have the current text. The cost sits with contributors instead: a change that moves a page has to be paired with a redirection entry, and a change that alters a heading changes an anchor that other sites may link to.

On licensing, the README states CC BY 4.0 for the repository while LICENSE-CODE is a separate file. CC BY 4.0 generally permits reuse with attribution, but the README does not say which paths fall under which file, and ThirdPartyNotices adds a third document. This is a description of what the repository contains, not legal advice. If you plan to republish the text or the code samples, read LICENSE, LICENSE-CODE and ThirdPartyNotices yourself.

Editorial conclusion

Adopt this repository if you maintain, translate or review WSL documentation, or if you want to read the source before it renders on Microsoft Learn. Do not clone it expecting to install WSL, build a kernel or file WSL runtime bugs; the README points runtime issues at the Microsoft/WSL tracker and console issues at Microsoft/Terminal. Before you open a pull request, verify three things: that your change belongs in WSL/ rather than the runtime repos, that the .openpublishing.publish.config.json docset layout still matches the folder you edited, and that the file you touched is covered by CC BY 4.0 rather than the LICENSE-CODE terms.

Frequently asked questions

Official sources

1. Issues
2. MicrosoftDocs/WSL on GitHub
3. Project website
4. README
5. Releases