A minimal root filesystem for running NixOS on the Windows Subsystem for Linux
NixOS-WSL is tested with the Windows Store version of WSL 2, which is now available on all supported Windows releases (both 10 and 11). Support for older "inbox" versions is best-effort.
First, download the latest release.
Then open up a Terminal, PowerShell or Command Prompt and run:
wsl --import NixOS .\NixOS\ nixos-wsl.tar.gz --version 2This sets up a new WSL distribution NixOS that is installed under
.\NixOS. nixos-wsl.tar.gz is the path to the file you
downloaded earlier. You might need to change this path or change to the download directory first.
You can now run NixOS:
wsl -d NixOSAfter the initial installation, you need to update your channels once, to be able to use nixos-rebuild:
nix-channel --updateIf you want to make NixOS your default distribution, you can do so with
wsl -s NixOSA recovery shell can be started with
wsl -d NixOS --system --user root -- /mnt/wslg/distro/bin/nixos-wsl-recoveryThis will load the WSL "system" distribution, activate your configuration,
then chroot into your NixOS system, similar to what nixos-enter would do
on a normal NixOS install.
You can choose an older generation to load with
wsl -d NixOS --system --user root -- /mnt/wslg/distro/bin/nixos-wsl-recovery --system /nix/var/nix/profiles/system-42-link(note that the path is relative to the new root)
This requires access to a system that already has Nix installed. Please refer to the Nix installation guide if that's not the case.
If you have a flakes-enabled Nix, you can use the following command to build your own tarball instead of relying on a prebuilt one:
sudo nix run github:nix-community/NixOS-WSL#nixosConfigurations.modern.config.system.build.tarballBuilderOr, if you want to build with local changes, run inside your checkout:
sudo nix run .#nixosConfigurations.your-hostname.config.system.build.tarballBuilderWithout a flakes-enabled Nix, you can build a tarball using:
nix-build -A nixosConfigurations.mysystem.config.system.build.tarballBuilder && sudo ./result/bin/nixos-wsl-tarball-builder
The resulting tarball can then be found under nixos-wsl.tar.gz.
Getting NixOS to run under WSL requires some workarounds:
- instead of directly loading systemd, we use a small shim that runs the NixOS activation scripts first
- some additional binaries required by WSL's internal tooling are symlinked to FHS paths on activation
Running on older WSL versions also requires a workaround to spawn systemd by hijacking the root shell and
spawning a container with systemd inside. This method of running things is deprecated and not recommended,
however still available as nixos-wsl-legacy.tar.gz or via wsl.nativeSystemd = false.
Apache License, Version 2.0. See LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html for details.