cli-walkthrough/01-navigation/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 — 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:

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

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)