# Installing WSL (Windows Subsystem for Linux)

This guide walks you through installing WSL on Windows 10 or 11. macOS and Linux users can skip this entirely.

---

## Step-by-step installation

### 1. Check your Windows version

Press `Win+R`, type `winver`, and press Enter. You need **Windows 10 build 19041 or later**, or **Windows 11**.

### 2. Open PowerShell as Administrator

This is important — a normal PowerShell window will not work.

- Click the **Start** button, type **PowerShell**
- Right-click **Windows PowerShell** and select **Run as administrator**
- Click **Yes** when prompted by User Account Control

Alternatively, right-click the Start button and choose **Terminal (Admin)**.

### 3. Install WSL

In the administrator PowerShell window, type:

```powershell
wsl --install
```

This single command does several things:

- Enables the WSL and Virtual Machine Platform features
- Downloads the latest Linux kernel
- Sets WSL 2 as the default version
- Downloads and installs Ubuntu

You should see progress output as it downloads and installs.

### 4. Restart your computer

When the install finishes, **restart your computer**. This is required — the features enabled in step 3 won't be active until you reboot.

### 5. Launch Ubuntu

After restarting, open the **Start** menu and search for **Ubuntu**. Click it to launch.

The first time you open Ubuntu, it will spend a minute or two decompressing files. This is normal — just wait.

### 6. Create your Linux username and password

Ubuntu will prompt you to create a new account:

```
Enter new UNIX username:
```

Pick a simple lowercase name with no spaces (e.g., `jsmith` or your UDel login).

Next, it will ask for a password. **Nothing will appear on screen while you type your password.** This is normal Linux behavior — it's not broken, it's just hiding your input for security. Type your password and press Enter. You'll be asked to confirm it.

### 7. Verify it's working

You should now see a Linux prompt that looks something like:

```
jsmith@DESKTOP-ABC123:~$
```

Try a few commands to confirm everything is working:

```bash
pwd
ls
whoami
```

### 8. Update your packages

It's good practice to update Ubuntu right after installing:

```bash
sudo apt update && sudo apt upgrade -y
```

You'll be prompted for the password you just created.

You're all set!

---

## Troubleshooting

### `wsl --install` just shows help text

This means WSL was already partially enabled on your machine (perhaps from a previous attempt). Instead, run:

```powershell
wsl --install -d Ubuntu
```

### The install hangs or stalls at 0%

Try downloading the distribution from the web instead:

```powershell
wsl --install --web-download -d Ubuntu
```

### "The virtual machine could not be started" (error 0x80370102)

Your computer's hardware virtualization may be disabled. You need to enable it in your BIOS/UEFI settings:

1. Restart your computer and enter the BIOS (usually by pressing `F2`, `F10`, `Del`, or `Esc` during boot — it varies by manufacturer)
2. Look for a setting called **Intel VT-x**, **Intel Virtualization Technology**, or **AMD-V** (usually under CPU or Advanced settings)
3. Enable it, save, and restart

### "WslRegisterDistribution failed" (error 0x8007019e)

The WSL feature itself isn't enabled. Open PowerShell as Administrator and run:

```powershell
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```

Then restart and try again.

### `wsl` is not recognized as a command

Make sure you're using a 64-bit PowerShell. Try typing `wsl.exe` instead of `wsl`.

### I forgot my Linux password

From PowerShell (not inside Ubuntu), run:

```powershell
wsl -u root
```

Then reset your password:

```bash
passwd your_username
```

---

## Launching WSL after installation

Once installed, you can open your Linux terminal in any of these ways:

- **Start menu**: Search for **Ubuntu**
- **PowerShell or Command Prompt**: Type `wsl`
- **Windows Terminal** (recommended): Ubuntu appears as an option in the dropdown tab menu. Windows Terminal supports multiple tabs and is a nicer experience overall.

---

## References

- [Install WSL (Microsoft docs)](https://learn.microsoft.com/en-us/windows/wsl/install)
- [Set up a WSL development environment](https://learn.microsoft.com/en-us/windows/wsl/setup/environment)
- [WSL troubleshooting (Microsoft docs)](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting)