How to Manually Install WSL on Windows When Automatic Setup Fails

As a Data Engineer, I spend most of my life in the terminal. Whether I'm optimizing Spark queries or building Python-based Gen AI tools, Windows Subsystem for Linux (WSL) is non-negotiable. It gives me the rich ecosystem of Linux with the productivity of Windows.

But setting it up on a fresh laptop isn't always smooth sailing.

We've all heard the advice: "Just open PowerShell and type wsl --install." Ideally, that single command enables all required Windows features, downloads Ubuntu, and sets everything up. But in the real world—especially on corporate laptops or fresh Windows installs—it often crashes and burns.

Recently, while setting up my new workstation, I hit a wall of cryptic error codes. Here is the exact path I took to go from a broken install to a production-ready Ubuntu environment.

---

The "Happy Path" Failure

I started with the standard command:

powershell
wsl --install

Result:

text
Installing: Ubuntu
An error occurred during installation. Distribution Name: 'Ubuntu'
Error Code: 0x80070520

This error code usually points to a Windows Store service failure or a generic permission issue, but the error message gives you zero help on how to fix it.

Here is the manual "nuclear option" that actually works.

---

Step 1: Manually Enable Windows Features (The DISM Method)

Since the automatic installer failed to enable the underlying tech, we have to do it manually using Deployment Image Servicing and Management (DISM).

Open PowerShell as Administrator and run these two commands. These enable the Linux Subsystem and the Virtual Machine Platform (required for WSL2).

powershell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

⚠️ Important: Restart your computer immediately after running these commands. WSL will not work until you do.

---

Step 2: Installing the Distro (Avoid the Generic Alias)

After the restart, I tried installing again. A common mistake is using the generic Ubuntu alias, which sometimes points to broken or old store links.

Instead, install a specific LTS version explicitly:

powershell
wsl --install -d Ubuntu-24.04

Note: If this CLI command still throws errors, open the Microsoft Store app, search for "Ubuntu 24.04 LTS", and click Install there. It bypasses the broken CLI downloader.

---

Step 3: The Kernel Error

Once Ubuntu finished downloading, I tried to launch it:

powershell
wsl

Result:

text
WslRegisterDistribution failed with error: 0x800701bc
Error: 0x800701bc WSL 2 requires an update to its kernel component.

This error means your Windows OS has the WSL "plumbing" enabled, but is missing the actual Linux kernel binary.

The Fix: Run this command in PowerShell (Admin):

powershell
wsl --update

If that hangs or fails (common on some networks), download the update manually from Microsoft:

• Download WSL2 Linux Kernel Update Package

After the update, set WSL 2 as your default version just to be safe:

powershell
wsl --set-default-version 2

---

Step 4: Verification (Don't Skip This)

Now, launch Ubuntu again. It should ask you to create a username and password. Once you are in, verify everything is correct.

1. Check WSL Version: Run this in PowerShell:

powershell
wsl -l -v

You should see:

text
  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2

If it says Version 1, you are running on the old, slow architecture. Run wsl --set-version Ubuntu-24.04 2 to upgrade it.

2. Check the Kernel: Run this inside Ubuntu:

bash
uname -r

It should return something ending in -microsoft-standard-WSL2.

---

Bonus: Cleanup "Ghost" Profiles

If you tried installing multiple times, you might see duplicate entries in your Windows Terminal dropdown (e.g., one "Ubuntu" and one "Ubuntu 24.04").

To fix this:

1. Open Windows Terminal Settings (Ctrl + ,).
2. Select the broken/duplicate profile on the left.
3. Scroll down and click Delete Profile.
4. This removes the shortcut without deleting your Linux data.

---

Summary Checklist

If wsl --install fails for you, don't waste time retrying it.

1. ✅ Enable Features: Use dism.exe commands.
2. ✅ Reboot: Mandatory.
3. ✅ Install: Use specific version (Ubuntu-24.04) or Microsoft Store.
4. ✅ Update Kernel: Run wsl --update to fix kernel errors.
5. ✅ Verify: Ensure wsl -l -v says Version 2.

Now you have a rock-solid foundation for your actual work.

Next up: Part 2: Configuring a production-grade Data Engineering environment in WSL (Zsh, Python, Antigravity).