wsl/README.md

   1 ---
   2 title: WSL + Linux
   3 homepage: https://docs.microsoft.com/en-us/windows/wsl/compare-versions
   4 tagline: |
   5   WSL (Windows Subsystem for Linux) lets you run Linux seemlessly on Windows.
   6 ---
   7
   8 ## Read Carefully!
   9
  10 1. Run **Windows Update** and reboot before attempting to install WSL.
  11 2. You will be prompted to give the installer **Admin** access.\
  12    WSL is an exception to our "no sudo" rule.
  13 3. You must **run the installer again**, after a **Restart**.\
  14    WSL 2 must be installed after WSL 1.
  15
  16 Since _WSL 2_ is not compatible with all system, _WSL 1_ is the _default_.
  17
  18 ## Cheat Sheet
  19
  20 > WSL lets you run Linux seemlessly on Windows.
  21 >
  22 > The Windows Subsystem for Linux has two modes:
  23 >
  24 > - **_WSL 1_** - a Windows Kernel syscall wrapper (similar to WINE)
  25 > - **_WSL 2_** - a true Linux Kernel run with Hyper-V virtualization
  26 >
  27 > Each mode has its
  28 > [tradeoffs](https://docs.microsoft.com/en-us/windows/wsl/compare-versions),
  29 > but the main differences are that WSL 1 has better compatibility with
  30 > inexpensive laptops and better seemless integration with the Windows file
  31 > system and that WSL 2 can run certain low-level software (such as for
  32 > networking and virtual file systems) that WSL 1 cannot.
  33
  34 Once installed,
  35 [Ubuntu Linux 20.04](https://www.microsoft.com/store/apps/9n6svws3rx71) will be
  36 available from the **Windows Start Menu**.
  37
  38 You can use the `wsl` command to start Ubuntu Linux with the `wsl` command, but
  39 only **after** clicking on it in the Windows Start Menu to add a `username` and
  40 `password`.
  41
  42 - **Username**: We recommend `app` as the username (this is a common convention)
  43   - The `root` (admin) account always exists, no matter what username you pick
  44 - **Password**: You can change the password at any time:
  45   - For `app`: `wsl -u root passwd app`
  46   - For `root`: `wsl -u root passwd`
  47
  48 ### How to Launch Linux
  49
  50 How to launch the default Linux:
  51
  52 ```pwsh
  53 wsl.exe
  54 ```
  55
  56 How to launch a specific Linux distribution with `-d`:
  57
  58 ```pwsh
  59 wsl.exe --list --verbose
  60 wsl.exe -d Ubuntu-20.04
  61 ```
  62
  63 **Note**: Linux is _NOT AVAILABLE_ until you complete the installation and
  64 create a username and password.
  65
  66 ### How to Set or Reset Linux Password
  67
  68 To reset the `root` password:
  69
  70 ```pwsh
  71 wsl -d Ubuntu-20.04 -u root passwd
  72 ```
  73
  74 To reset the `app` user's password:
  75
  76 ```pwsh
  77 wsl -d Ubuntu-20.04 -u root passwd app
  78 ```
  79
  80 ### How to Run a Single Linux Command
  81
  82 Assuming you want to run `ls ~/` as the default user:
  83
  84 ```pwsh
  85 wsl -- ls ~/
  86 ```
  87
  88 Assuming your username is `app` and you wanted to run `ls`:
  89
  90 ```pwsh
  91 wsl -d Ubuntu-20.04 -u app -- ls ~/
  92 ```
  93
  94 ### How to Switch Between WSL 1 and WSL 2
  95
  96 Despite the name, WSL 2 is neither a "better" version of nor a replacement for
  97 WSL 1. Rather WSL 1 uses a syscall wrapper (much like WINE) whereas WSL 2 uses
  98 Hyper-V virtualization.
  99
 100 You can start a Linux install in either mode and switch between the two as
 101 desired.
 102
 103 Either by setting the per Linux install:
 104
 105 ```pwsh
 106 wsl --list --verbose
 107 ```
 108
 109 ```pwsh
 110 wsl --set-version Ubuntu-20.04 1
 111 # or
 112 wsl --set-version Ubuntu-20.04 2
 113 ```
 114
 115 Or by setting the global default:
 116
 117 ```pwsh
 118 wsl --set-default-version 1
 119 # or
 120 wsl --set-default-version 2
 121 ```
 122
 123 Note that you _cannot_ set the mode before rebooting.
 124
 125 See also <https://docs.microsoft.com/en-us/windows/wsl/wsl2-index>.
 126
 127 ### How to Install WSL with PowerShell
 128
 129 1. Install WSL 1 + parts of WSL 2
 130
 131    ```pwsh
 132    # Install WSL 1
 133    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
 134
 135    # Install VirtualMachinePlatform for WSL 2
 136    dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
 137    ```
 138
 139 2. Install Ubuntu Linux
 140
 141    ```pwsh
 142    # Install Ubunut Linux
 143    curl.exe -L -o Ubuntu_2004_x64.appx https://aka.ms/wslubuntu2004
 144    powershell Add-AppxPackage Ubuntu_2004_x64.appx
 145    ```
 146
 147 3. Reboot
 148
 149 4. Finish installing WSL 2 (copying the `kernel` twice for good measure)
 150
 151    ```pwsh
 152    # Download and Install the WSL 2 Update (contains Microsoft Linux kernel)
 153    & curl.exe -f -o wsl_update_x64.msi "https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi"
 154    powershell -Command "Start-Process msiexec -Wait -ArgumentList '/a ""wsl_update_x64.msi"" /quiet /qn TARGETDIR=""C:\Temp""'"
 155    Copy-Item -Path "$env:TEMP\System32\lxss" -Destination "C:\System32" -Recurse
 156
 157    # Also install the WSL 2 update with a normal full install
 158    powershell -Command "Start-Process msiexec -Wait -ArgumentList '/i','wsl_update_x64.msi','/quiet','/qn'"
 159    ```
 160
 161 5. Then click Ubuntu Linux in the start menu.
 162
 163 See also:
 164
 165 - <https://github.com/microsoft/WSL/issues/5014#issuecomment-692432322>
 166 - <https://docs.microsoft.com/en-us/windows/wsl/install-manual>.
 167
 168 ### Errors: Feature Not Installed & Nested VMs
 169
 170 The most likely problem is that you're on a computer that does not support WSL 2
 171 (or the necessary VT-x options have been disabled).
 172
 173 The simplest workaround is to switch back to WSL 1:
 174
 175 ```pwsh
 176 wsl --set-default-version 1
 177 wsl --set-version Ubuntu-20.04 1
 178 ```
 179
 180 See also <https://webinstall.dev/wsl2> (errors section).
 181
 182 ## References
 183
 184 - https://docs.microsoft.com/en-us/windows/wsl/install-win10
 185 - https://github.com/microsoft/WSL/issues/5014
 186 - https://docs.microsoft.com/en-us/windows/wsl/wsl2-index
 187 - https://aka.ms/wsl2kernel
 188 - https://docs.microsoft.com/en-us/windows/wsl/install-manual