Running a fully declarative and reproducible Linux environment on Windows used to mean juggling virtual machines or complicated dual-boot setups. NixOS-WSL breaks that mold by bringing NixOS—a Linux distribution famed for its declarative system configuration and unique package manager—directly into the Windows Subsystem for Linux (WSL). This project makes it possible to run NixOS on Windows seamlessly, without the overhead of a separate VM or reboot.
what nixos-wsl does and how it integrates nixos with windows
NixOS-WSL provides a method to run a genuine NixOS environment inside Windows through WSL. Instead of a traditional Linux distribution shipped with WSL, it uses the declarative configuration and reproducibility principles of NixOS. The key benefit is that users get all the power of NixOS’s package management and system configuration directly on their Windows machines.
Under the hood, this project uses WSL 2’s lightweight virtualization and containerization capabilities. WSL 2 runs a real Linux kernel in a lightweight VM, which allows NixOS to run natively without emulation. The repo supplies a prebuilt nixos.wsl image that can be installed within WSL, simplifying what would otherwise be a complex setup.
The architecture revolves around three pillars:
- WSL 2 kernel and runtime: Provides the Linux environment on Windows.
- NixOS system configuration: The declarative Nix expressions that define the system state.
- Integration scripts and tooling: Facilitate installation and launching of the NixOS system inside WSL.
The stack is primarily Nix expressions, shell scripts, and WSL utilities, with the system leveraging the official NixOS configuration language to describe and build the environment.
technical strengths and architectural tradeoffs
What distinguishes NixOS-WSL is how it blends NixOS’s declarative, reproducible approach with the Windows developer workflow via WSL. The code is surprisingly clean and opinionated: it focuses on providing a smooth experience without attempting to reinvent WSL or NixOS itself.
Key technical strengths include:
Declarative system setup: Unlike typical WSL distros, which often require manual package management inside the shell, NixOS-WSL leverages NixOS’s declarative configurations. This means your environment is reproducible and version-controlled.
Reproducible builds and environments: Thanks to Nix, packages and system states are reproducible. This reduces “works on my machine” issues.
Minimal user setup: The project provides a single downloadable
.wslpackage that you just double-click to install, removing many manual steps.Lightweight virtualization: WSL 2 is more resource-efficient than running a full VM, offering near-native Linux kernel performance.
However, there are tradeoffs and limitations worth noting:
WSL constraints: WSL is not a full Linux kernel environment. Some low-level kernel features or hardware access might be limited or behave differently.
Windows integration quirks: Interoperability between Windows and the NixOS environment can be tricky, especially for GUI apps or certain networking setups.
Configuration complexity: While NixOS is powerful, its declarative configuration language has a learning curve. Users unfamiliar with Nix may find initial setup challenging.
No native systemd support in WSL: NixOS relies heavily on systemd for service management, but WSL historically has limited or no systemd support, which might affect some services or workflows.
Overall, the architecture is a practical compromise: it brings NixOS’s strengths into Windows with minimal overhead, accepting some of WSL’s inherent limitations.
quick start with nixos-wsl
Run the following from powershell:
- Enable WSL if you haven’t done already:
wsl --install --no-distribution
Download
nixos.wslfrom the latest release.Double-click the file you just downloaded (requires WSL >= 2.4.4)
You can now run NixOS:
wsl -d NixOS
For more detailed instructions, refer to the documentation.
verdict: who should consider nixos-wsl
NixOS-WSL is a solid option for Windows users who want to leverage NixOS’s declarative configuration and reproducible builds without leaving the Windows ecosystem or managing a separate VM. It’s especially relevant for developers and power users who already use WSL and want a more predictable, version-controlled Linux environment.
That said, it’s not a drop-in replacement for a full Linux machine or VM. WSL’s limitations around systemd, hardware access, and networking mean some workflows might be constrained or require workarounds. Also, newcomers to NixOS should be ready to invest time learning its configuration language.
If you value reproducibility and declarative configuration, and you want to avoid the overhead of dual boot or heavy virtualization, NixOS-WSL offers a pragmatic and elegant solution. The project’s clean implementation and straightforward installation make it worth exploring for anyone interested in advanced Linux environments on Windows.
Related Articles
- Hatchet: durable background task orchestration with Go and Postgres — Hatchet offers a durable, fault-tolerant background task and workflow engine built with Go and Postgres. It supports com
- OpenAI Codex CLI: local-first AI coding assistant with ChatGPT integration — OpenAI Codex CLI brings AI coding assistance local to your terminal, integrating with ChatGPT plans for powerful hybrid
→ GitHub Repo: nix-community/NixOS-WSL ⭐ 2,873 · Nix