wsl/README.md

   1 ---
   2 title: WSL (Complete)
   3 homepage: https://docs.microsoft.com/en-us/windows/wsl/wsl2-index
   4 tagline: |
   5   WSL (Windows Subsystem for Linux) 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** before WSL can be used.
  12 3. Not all systems can use WSL 2, so **WSL 1** is the **default**.
  13
  14 ## Cheat Sheet
  15
  16 > This is a complete WSL installer that includes **_WSL 1_**, **_WSL 2_**
  17 > (Hyper-V), and **_Ubuntu Linux_**.
  18 >
  19 > WSL 2 is not "version 2" of WSL, but more "layer 2" WSL 1 uses a Linux syscall
  20 > wrapper around the Windows Kernel WSL 2 uses `VirtualMachinePlatform` and
  21 > Hyper-V to run a full Linux kernel with 100% syscall compatibility.
  22
  23 After installing WSL and **Rebooting** you will be able to install Linux
  24 variants from the Windows 10 Store:
  25
  26 - [Ubuntu Linux 20.04](https://www.microsoft.com/store/apps/9n6svws3rx71)
  27 - [Alpine WSL](https://www.microsoft.com/store/apps/9p804crf0395)
  28
  29 ### How to Launch Linux
  30
  31 To Launch the default Linux:
  32
  33 ```pwsh
  34 wsl.exe
  35 ```
  36
  37 To Launch a specific Linux:
  38
  39 ```pwsh
  40 wsl.exe --list
  41 wsl.exe -d Ubuntu-20.04
  42 ```
  43
  44 ### How to Set or Reset Root Password
  45
  46 ```pwsh
  47 wsl -d Ubuntu-20.04 -u root passwd
  48 ```
  49
  50 ### How to Run a Single Command
  51
  52 Assuming you want to run `ls ~/` as the default user:
  53
  54 ```pwsh
  55 wsl -- ls ~/
  56 ```
  57
  58 Assuming your username is `app` and you wanted to run `ls`:
  59
  60 ```pwsh
  61 wsl -d Ubuntu-20.04 -u app -- ls ~/
  62 ```
  63
  64 ### How to Switch Between WSL 1 and WSL 2
  65
  66 Despite the name, WSL 2 is neither a "better" version of nor a replacement for
  67 WSL 1. Rather WSL 1 uses a syscall wrapper (much like WINE) whereas WSL 2 uses
  68 Hyper-V virtualization.
  69
  70 You can start a Linux install in either mode and switch between the two as
  71 desired.
  72
  73 Either by setting the per Linux install:
  74
  75 ```pwsh
  76 wsl --list --verbose
  77 ```
  78
  79 ```pwsh
  80 wsl --set-version Ubuntu-20.04 1
  81 # or
  82 wsl --set-version Ubuntu-20.04 2
  83 ```
  84
  85 Or by setting the global default:
  86
  87 ```pwsh
  88 wsl --set-default-version 1
  89 # or
  90 wsl --set-default-version 2
  91 ```
  92
  93 Note that you _cannot_ set the mode before rebooting.
  94
  95 See also <https://docs.microsoft.com/en-us/windows/wsl/wsl2-index>.
  96
  97 ### How to Install Linux with PowerShell
  98
  99 You can download Linux from the Windows Store, or with `curl.exe` on the Command
 100 Line:
 101
 102 ```pwsh
 103 curl.exe -L -o Ubuntu_2004_x64.appx https://aka.ms/wslubuntu2004
 104 powershell Add-AppxPackage Ubuntu_2004_x64.appx
 105 ```
 106
 107 See also <https://docs.microsoft.com/en-us/windows/wsl/install-manual>.
 108
 109 ### Raw PowerShell Install Commands
 110
 111 This is already detailed at [webinstall.dev/wsl1](https://webinstall.dev/wsl1)
 112 and [webinstall.dev/wsl2](https://webinstall.dev/wsl2)
 113
 114 See also <https://github.com/microsoft/WSL/issues/5014>
 115
 116 ### Errors: Feature Not Installed & Nested VMs
 117
 118 These errors are detailed at <https://webinstall.dev/wsl2>.
 119
 120 Likely solution:
 121
 122 ```pwsh
 123 wsl --set-default-version 1
 124 wsl --set-version Ubuntu-20.04 1
 125 ```
 126
 127 ## References
 128
 129 - https://docs.microsoft.com/en-us/windows/wsl/install-win10
 130 - https://github.com/microsoft/WSL/issues/5014
 131 - https://docs.microsoft.com/en-us/windows/wsl/wsl2-index
 132 - https://aka.ms/wsl2kernel
 133 - https://docs.microsoft.com/en-us/windows/wsl/install-manual