NixOS on WSL
A minimal root filesystem for running NixOS on WSL. It can be used with
DistroLauncher as
install.tar.gz or as input to wsl --import --version 2.
System requirements
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.
Quick start
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 NixOSIf you want to make NixOS your default distribution, you can do so with
wsl -s NixOSTroubleshooting
A 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)
Building your own system tarball
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.
Design
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.
License
Apache License, Version 2.0. See LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html for details.