wsl2/README.md

   1 ---
   2 title: WSL 2 (Hyper-V)
   3 homepage: https://docs.microsoft.com/en-us/windows/wsl/wsl2-index
   4 tagline: |
   5   WSL2 (Windows Subsystem for Linux 2) runs a true Linux kernel via Hyper-V virtualization.
   6 ---
   7
   8 ## Read Carefully!
   9
  10 1. WSL is a **system** service which **requires Admin privileges** to install.
  11 2. A **System Reboot** is required **inbetween** install steps.
  12
  13 ## Cheat Sheet
  14
  15 > WSL 2 uses `VirtualMachinePlatform` and Hyper-V to run a full Linux kernel
  16 > with 100% syscall compatibility. However, it does not work on all computers
  17 > and may not work in nested Virtual Machines - such as if running Windows in
  18 > VirtualBox or Parallels on Mac or Linux.
  19
  20 This will install **WSL 1 and WSL 2 ONLY**.
  21
  22 **Most people** want [WSL 1 + WSL 2 + Linux](https://webinstall.dev/wsl). \
  23 (WSL 2 is NOT a replacement for WSL 1, it's just another _layer_ of WSL)
  24
  25 See the **Full Cheat Sheet** at <https://webinstall.dev/wsl>.
  26
  27 ### How to Install Linux
  28
  29 Once WSL is installed you can download Linux from the Windows Store. We
  30 recommend:
  31
  32 - [Ubuntu Linux 20.04](https://www.microsoft.com/store/apps/9n6svws3rx71)
  33 - [Alpine WSL](https://www.microsoft.com/store/apps/9p804crf0395)
  34
  35 ### How to Switch to WSL 2 Manually
  36
  37 To set WSL 2 for a specific Linux installation:
  38
  39 1. List all installed Linux versions
  40    ```pwsh
  41    wsl --list --verbose
  42    ```
  43 2. Set the desired version to WSL 2 with `--set-version`. For example:
  44    ```pwsh
  45    wsl --set-version Ubuntu-20.04 2
  46    ```
  47
  48 If WSL 2 works on your computer, you may set it as the default:
  49
  50 ```pwsh
  51 wsl --set-default-version 2
  52 ```
  53
  54 ### How to install WSL 2 with PowerShell
  55
  56 If you'd like to install manually, or create your own script, this is how we do
  57 it:
  58
  59 ```pwsh
  60 # Install WSL 1
  61 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  62
  63 # Install VirtualMachinePlatform
  64 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  65
  66 # Download and Install the WSL 2 Update (contains Microsoft Linux kernel)
  67 & curl.exe -f -o wsl_update_x64.msi "https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi"
  68 powershell -Command "Start-Process msiexec -Wait -ArgumentList '/a ""wsl_update_x64.msi"" /quiet /qn TARGETDIR=""C:\Temp""'"
  69 Copy-Item -Path "$env:TEMP\System32\lxss" -Destination "C:\System32" -Recurse
  70
  71 # Also install the WSL 2 update with a normal full install
  72 powershell -Command "Start-Process msiexec -Wait -ArgumentList '/i','wsl_update_x64.msi','/quiet','/qn'"
  73 ```
  74
  75 See also <https://github.com/microsoft/WSL/issues/5014#issuecomment-692432322>
  76
  77 ### Error: Required Feature Not Installed
  78
  79 > Installing, this may take a few minutes...
  80 >
  81 > Error: 0xXXXXXXXX The virtual machine could not be started because a required
  82 > feature is not installed.
  83
  84 It may be that your computer does not support virtualization because:
  85
  86 - it lacks hardware support in the CPU for VTx
  87 - VTx is disabled in the BIOS or EFI
  88 - Virtualization has disabled in Windows 10
  89
  90 You should switch back to WSL 1 until you solve this problem:
  91
  92 ```pwsh
  93 wsl --set-default-version 1
  94 wsl --list --verbose
  95 wsl --set-version Ubuntu-20.04 1
  96 ```
  97
  98 ### Error: Nested Virtual Machines
  99
 100 WSL2 may not work properly if you are already running Windows inside of a
 101 Virtual Machine, especially if MacOS or Linux is the VM Host.
 102
 103 ## References
 104
 105 - https://docs.microsoft.com/en-us/windows/wsl/install-win10
 106 - https://github.com/microsoft/WSL/issues/5014
 107 - https://docs.microsoft.com/en-us/windows/wsl/wsl2-index
 108 - https://aka.ms/wsl2kernel
 109 - https://docs.microsoft.com/en-us/windows/wsl/install-manual