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 emulation.
   6 ---
   7
   8 ## Cheat Sheet
   9
  10 > WSL 2 uses `VirtualMachinePlatform` and Hyper-V to run a full Linux kernel
  11 > with 100% syscall compatibility.
  12
  13 After installing WSL and **Rebooting** you will be able to install Linux
  14 variants from the Windows 10 Store:
  15
  16 - [Ubuntu Linux 20.04](https://www.microsoft.com/store/apps/9n6svws3rx71)
  17 - [Alpine WSL](https://www.microsoft.com/store/apps/9p804crf0395)
  18
  19 ### Admin Privileges Required
  20
  21 It is not possible to install WSL without Admin privileges.
  22
  23 You _will_ need to allow the installer to run as Admin when asked.
  24
  25 ### Reboot Required
  26
  27 You will not be able to use WSL without rebooting.
  28
  29 ### How to Install Linux Bash
  30
  31 You can download Linux from the Windows Store, or from the Command Line:
  32
  33 ```pwsh
  34 curl.exe -L -o Ubuntu_2004_x64.appx https://aka.ms/wslubuntu2004
  35 powershell Add-AppxPackage Ubuntu_2004_x64.appx
  36 ```
  37
  38 See also <https://docs.microsoft.com/en-us/windows/wsl/install-manual>.
  39
  40 ### How to Launch Linux
  41
  42 To Launch the default Linux:
  43
  44 ```pwsh
  45 wsl.exe
  46 ```
  47
  48 To Launch a specific Linux:
  49
  50 ```pwsh
  51 wsl.exe --list
  52 wsl.exe -d Ubuntu-20.04
  53 ```
  54
  55 ### How to Set or Reset Root Password
  56
  57 ```pwsh
  58 wsl -d Ubuntu-20.04 -u root passwd
  59 ```
  60
  61 ### How to Run a Single Command
  62
  63 Assuming you want to run `ls ~/` as the default user:
  64
  65 ```pwsh
  66 wsl -- ls ~/
  67 ```
  68
  69 Assuming your username is `app` and you wanted to run `ls`:
  70
  71 ```pwsh
  72 wsl -d Ubuntu-20.04 -u app -- ls ~/
  73 ```
  74
  75 ### How to Switch Between WSL 1 and WSL 2
  76
  77 Despite the name, WSL 2 is neither a "better" version of nor a replacement for
  78 WSL 1. Rather WSL 1 uses a syscall wrapper (much like WINE) whereas WSL 2 uses
  79 Hyper-V virtualization.
  80
  81 After rebooting you can set WSL 2 as the default:
  82
  83 ```pwsh
  84 wsl --set-default-version 2
  85 ```
  86
  87 You can list your existing WSL Linuxes:
  88
  89 ```pwsh
  90 wsl --list --verbose
  91 ```
  92
  93 And you can switch between using WSL and WSL 2 without an issues:
  94
  95 ```pwsh
  96 wsl --set-version Ubuntu 2
  97 ```
  98
  99 See also <https://docs.microsoft.com/en-us/windows/wsl/wsl2-index>.
 100
 101 ### Raw PowerShell Install Commands
 102
 103 If you'd like to install manually, or create your own script, this is how we do
 104 it:
 105
 106 ```pwsh
 107 # Install WSL 1
 108 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
 109
 110 # Install VirtualMachinePlatform
 111 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
 112
 113 # Download and Install WSL Update (contains Microsoft Linux kernel)
 114 & curl.exe -f -o wsl_update_x64.msi "https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi"
 115 powershell -Command "Start-Process msiexec -Wait -ArgumentList '/a wsl_update_x64.msi /qb TARGETDIR=""$env:TEMP""'"
 116 Copy-Item -Path "$env:TEMP\System32\lxss" -Destination "C:\System32" -Recurse
 117 ```
 118
 119 See also <https://github.com/microsoft/WSL/issues/5014>
 120
 121 ### Nested VMs
 122
 123 WSL2 may not work properly if you are already running Windows inside of a
 124 Virtual Machine, especially if MacOS or Linux is the VM Host.
 125
 126 ## References
 127
 128 - https://docs.microsoft.com/en-us/windows/wsl/install-win10
 129 - https://github.com/microsoft/WSL/issues/5014
 130 - https://docs.microsoft.com/en-us/windows/wsl/wsl2-index
 131 - https://aka.ms/wsl2kernel
 132 - https://docs.microsoft.com/en-us/windows/wsl/install-manual