computing-setup/WSL.md

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:

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. Wait it out.

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 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:

pwd
ls
whoami

8. Update your packages

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

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:

wsl --install -d Ubuntu

The install hangs or stalls at 0%

Try downloading the distribution from the web instead:

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; this 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:

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:

wsl -u root

Then reset your password:

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)
• Set up a WSL development environment
• WSL troubleshooting (Microsoft docs)