NixOS-WSL: running a full NixOS system inside Windows Subsystem for Linux

The install is a file you double-click, not a script you run

The quick start has four steps and step two is the one that surprises people who expect a curl-pipe-to-shell installer. You download `nixos.wsl` from the latest release page and double-click it. That is the whole installation mechanism, and it only works because of what a `.wsl` file is: WSL treats it as a distribution archive and installs it like a downloaded distro, which means you never run a shell script as an administrator and never edit a Linux-side install script by hand.

The prerequisite is that WSL itself exists but has no distribution installed yet. The README's first command is:

wsl --install --no-distribution

The `--no-distribution` flag is the point. It enables the WSL platform without dropping Ubuntu or another default distro on your machine, so you end up with WSL as a feature and NixOS as the only thing inside it. After the double-click, the distro registers itself under the name `NixOS` and you enter it with:

wsl -d NixOS

One constraint is stated explicitly and it is the kind of detail that decides whether the double-click does anything: it requires WSL 2.4.4 or newer. Nothing in the error message will tell you that, so a user on an older WSL build gets a file that will not open and has to check their WSL version themselves.

What is actually in the repository: modules behind a flake

The tree shows a normal NixOS system configuration rather than a bespoke installer project. There is a `flake.nix` and a matching `flake.lock`, plus a plain `default.nix`, which means the project can be consumed both as a flake and as a traditional Nix expression. A `VERSION` file at the root carries the release string that ends up in the installed system, and `modules/` is where the configuration that distinguishes a WSL NixOS from any other NixOS lives.

The supporting directories are informative. `checks/` and `tests/` are separate, which tells you the project distinguishes its own verification from the broader NixOS test suite. `utils/` holds helper scripts, `assets/` holds the artwork including the SVG logo the README renders, and `docs/` is the source for the documentation site.

There is also an `.envrc`, which is a direnv file. Its presence tells you contributors are expected to work inside a development shell rather than against a globally installed Nix, and a `.vscode/` directory alongside it means the editor configuration is committed for that setup.

The absence of a large program is the point. A WSL distribution is an assembled root filesystem plus configuration, so almost all the code you would expect lives upstream in NixOS, and this repository's job is the delta that makes it run inside a Windows kernel interface.

Version tags are date-based and publishing lags them

The three releases on record are `2505.7.0` on 2025-08-11, `2511.7.1` on 2026-03-01, and `2605.7.2` on 2026-06-06. Read the leading four digits as a year and month, which makes `2605` mean May 2026 and `2511` mean November 2025. That is a useful convention here because the tag tells you which NixOS generation the distribution was cut from, not just when the build ran.

The interesting detail is the gap between the version date and the publish date. `2505` shipped in August 2025, four months later. `2511` was published on 2026-03-01, which is four months after its own date as well. `2605.7.2` was published on 2026-06-06, about a month after. So the pattern is a delay of weeks to months between the version being fixed and the artifact becoming downloadable.

The practical consequence is that the download you get is not the freshest commit. The last push was on 2026-09-22, roughly three and a half months after `2605.7.2` was published, so a meaningful amount of work is sitting on `main` without a release behind it. For a distribution whose whole job is to hand you a known-good artifact, that gap is the thing to watch rather than the star count or the version number.

What you give up by staying inside WSL

WSL2 runs Linux in a lightweight virtual machine managed by Windows, which is the source of both its appeal and its limits. The appeal is that you get a real Linux userland, a real init, and Nix's declarative model, while keeping a Windows machine you can still dual-boot or repair. A broken configuration can be replaced from outside.

The limits follow from that architecture. Anything requiring privileged kernel features, cgroup manipulation or full device access will behave differently inside WSL than on a bare-metal NixOS installation. Docker is the most common example people ask about, and it works differently enough that it needs its own configuration work. GUI applications need a display path from Windows into the distribution, which is a separate setup problem from installing NixOS. Filesystem performance across the Windows boundary is another recurring complaint in any WSL setup.

None of this makes WSL the wrong choice. It makes it a different trade from installing NixOS on hardware. If your work is building Rust, Python or Node projects where the toolchain is the variable being managed, Nix inside WSL removes the worst part of that problem. If your work needs kernel modules, custom storage or a service that expects to own the machine, it does not.

Where this fits against other ways to get Nix

There are two obvious alternatives, and the choice comes down to how much of your machine you want to hand over. Installing NixOS proper replaces the operating system. It gives you the full declarative system, the boot loader and the hardware story, and it is the better answer if you are willing to commit a machine to it. The cost is that it is not reversible in the way adding a subsystem is.

The other alternative is installing Nix's package manager on top of an existing Ubuntu or other WSL distribution, which the README never proposes and which the project's existence is an argument against. That route gives you `nix` and per-project `shell.nix` files without the system-level profile, and it is much lighter. What it does not give you is a system that is itself declared, which is where the rollback and reproducibility story comes from.

NixOS-WSL sits between those, and its contribution is specifically the packaging. Making NixOS a `.wsl` file that installs by double-click means you get the declarative system without giving up Windows, and it sidesteps the usual friction of getting a NixOS image onto a machine. What it does not add is anything NixOS itself lacks. If you need a feature from NixOS that this distribution does not configure, the answer is in NixOS upstream rather than here.

Documentation does the work the README does not

The README is one screen long and points at `https://nix-community.github.io/NixOS-WSL` twice, once as the documentation link and once at the install page for more detailed instructions. That is the correct division of labour for a distribution project, and it is also the honest description of where the answers live: the repository gives you the artifact, the documentation site gives you the configuration.

The maintainer is named in the repository description as `@nzbr`, and the project sits under the `nix-community` organisation rather than the NixOS project itself, which is a reasonable signal about its status and its relationship to upstream. A Matrix room is linked from the README header for support.

For an evaluation, the useful check is whether the documentation covers the configuration you actually need. The quick start proves the distribution installs and starts. Whether you can get a GUI toolkit, a container runtime, a Home Manager configuration or an X server working is decided on the documentation site and in the modules that the flake exports, not in the README.

Editorial conclusion

NixOS-WSL earns its place when you are on Windows, want Nix's declarative packages and rollbacks, and do not want to repartition your disk or learn a second bootloader. The install is genuinely short, the repository carries real configuration in modules/ behind a flake, and the last push on 2026-09-22 shows the work is current. Two things to check first: whether your WSL build meets the documented minimum of 2.4.4, and whether the features you need, GUI apps, Docker, an X server, Home Manager, are configured by the documentation site rather than by the quick start. The README is an installer guide, not a manual, and it hands you off to the documentation at the first step that needs explaining.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nix-community/NixOS-WSL on GitHub
4. README
5. Releases