DOCSEARCHbyAlgolia
Submit Docs

NixOS-WSL Documentation

repository·main·Indexed 25 days ago

https://github.com/nix-community/nixos-wsl

Modules and tools to run NixOS within the Windows Subsystem for Linux (WSL). Includes guides for installation via .wsl files or custom tarballs, configuration using Nix Flakes, managing default users, and troubleshooting with recovery shells. Provides specific instructions for integrating VSCode Remote using nix-ld or the vscode-remote-workaround module.

Tokens
2.7K
Snippets
15
Records
17
Agent score
85%

What's inside NixOS-WSL

  1. Install NixOS-WSL (Older WSL versions)

    main

    If you are using a WSL version older than 2.4.4, you must manually import the distribution using the wsl --import command. This example installs the distribution named NixOS into a directory named NixOS within your user profile.

    Note: nixos.wsl refers to the file downloaded from the latest release (previously named nixos-wsl.tar.gz in versions prior to 2411).

    wsl --import NixOS $env:USERPROFILE\NixOS nixos.wsl --version 2

  2. Start a recovery shell with a specific system generation

    main

    To recover using an older system generation, use the --system flag with the path to the desired generation profile. Note that the path provided must be relative to the new root of the chroot environment.

    wsl -d NixOS --system --user root -- /mnt/wslg/distro/bin/nixos-wsl-recovery --system /nix/var/nix/profiles/system-42-link

  3. Install NixOS-WSL (WSL 2.4.4 or later)

    main

    For WSL version 2.4.4 or later, you can install NixOS-WSL by double-clicking the downloaded .wsl file or by using the wsl --install --from-file command in PowerShell.

    By default, the distribution is registered as NixOS. You can customize the registration name using the --name flag and the disk image storage location using the --location flag.

    wsl --install --from-file nixos.wsl

  5. Start a recovery shell for NixOS WSL

    main

    If your NixOS WSL instance is failing to boot or requires manual intervention, you can start a recovery shell. This command loads the WSL 'system' distribution, activates your configuration, and then chroots into your NixOS system (functionally similar to nixos-enter on a standard NixOS installation).

    wsl -d NixOS --system --user root -- /mnt/wslg/distro/bin/nixos-wsl-recovery

  6. Change the default WSL username

    main

    To change the default username from nixos to a different name, use the wsl.defaultUser option in your NixOS configuration.

    For new installations: When building a custom tarball, setting wsl.defaultUser is sufficient; the specified user will be created automatically during the build process.

    For existing installations: If you have already installed NixOS on WSL, follow these steps to ensure the change is applied correctly:

    1. Edit your configuration: sudo nixos-rebuild edit.
    2. Update the wsl.defaultUser setting to your desired username in /etc/nixos/configuration.nix.
    3. Apply the configuration using sudo nixos-rebuild boot. Warning: Do not use nixos-rebuild switch, as it may cause the new user account to be misconfigured.
    4. Exit the NixOS shell and stop the WSL distribution: wsl -t NixOS.
    5. Start a shell as root and immediately exit to apply the new generation: wsl -d NixOS --user root exit.
    6. Stop the distribution again: wsl -t NixOS.
    7. Open a new WSL shell to use your new username.

  7. Quick Start: Install NixOS on WSL

    main

    To run NixOS on the Windows Subsystem for Linux (WSL), follow these steps from PowerShell:

    1. Enable WSL: If WSL is not already enabled, run:
      wsl --install --no-distribution
    2. Download the Image: Download the nixos.wsl file from the latest release.
    3. Install: Double-click the downloaded nixos.wsl file. Note that this requires WSL version 2.4.4 or higher.
    4. Launch: Once installed, you can enter your NixOS instance using:
      wsl -d NixOS
    wsl --install --no-distribution
# After downloading nixos.wsl and double-clicking it:
wsl -d NixOS

  8. Set user password and update Nix channels

    main

    After installation, perform these two steps to ensure your environment is usable:

    1. Set a password: The default user is nixos (member of the wheel group). Since security.sudo.wheelNeedsPassword is true by default, you must set a password to use sudo.
    2. Update channels: You must update your channels once to enable the use of nixos-rebuild.

    To access your environment, run wsl -d NixOS (or your custom distribution name).

  9. Patch the VSCode server using vscode-remote-workaround

    main

    Alternatively, you can replace the nodejs binary shipped with the VSCode server with one from the Nixpkgs nodejs package. This method is less intrusive to other programs but can be more brittle during updates.

    To use this method:

    1. Add the vscode-remote-workaround module to your configuration. If using Flakes, add the repository as a flake input. If not using Flakes, copy the module file to your configuration and add it to your imports.
    2. Enable the module in your configuration.
    vscode-remote-workaround.enable = true;

  10. Build your own NixOS-WSL system tarball

    main

    If you have a flakes-enabled Nix, you can build a custom system tarball instead of using a prebuilt one. This is useful for custom configurations.

    To build using the remote repository:

    sudo nix run github:nix-community/NixOS-WSL#nixosConfigurations.default.config.system.build.tarballBuilder

    To build using a local checkout (to include local changes):

    sudo nix run .#nixosConfigurations.your-hostname.config.system.build.tarballBuilder

    If you are not using flakes, use nix-build to generate the builder and then execute it:

    nix-build -A nixosConfigurations.default.config.system.build.tarballBuilder && sudo ./result/bin/nixos-wsl-tarball-builder

    The resulting tarball will be located under nixos.wsl.

    sudo nix run github:nix-community/NixOS-WSL#nixosConfigurations.default.config.system.build.tarballBuilder