How to Install and Set Up WSL on Windows

Getting started with the Windows Subsystem for Linux (WSL) might sound intimidating, but it’s surprisingly straightforward. Whether you’re a developer aiming to streamline your workflow or just curious about using Linux tools on Windows, the setup process is quick and hassle-free. Below, we’ll walk you through the steps to check compatibility, install WSL, and customize it to your needs.

Checking Windows Version Compatibility

Before installing WSL, it’s important to confirm your Windows version supports it. WSL is only available on Windows 10 (build 19041 or higher) and Windows 11. Verifying your version takes just a few seconds:

1. Press Win + R to open the Run dialog box.
2. Type winver and hit Enter.

A pop-up window will display your Windows version and build number. If your machine is running an older version of Windows, you’ll need to update it to proceed. Windows updates ensure compatibility and provide the latest features for WSL.

Installing WSL Through PowerShell

Microsoft has made installing WSL incredibly easy with a simple command. Open PowerShell with administrator privileges to get started:

1. Click the Start Menu, type PowerShell, and select Run as Administrator.

2. Type the following command and press Enter:

   wsl --install
   

This command automatically enables the required features, downloads the default Linux distribution (Ubuntu), and completes the setup for you. Once it finishes, restart your computer if prompted. When your system boots back up, you’ll have WSL and a functional Linux terminal ready to go.

Curious about what this command does? It’s a one-stop solution that handles everything behind the scenes, eliminating manual configurations and streamlining the process.

Installing a Specific Linux Distribution

If you prefer a different Linux distribution or want to explore your options, WSL allows you to choose from a variety of Linux distros. Here’s how to pick and install one:

1. First, list all available distributions by running:

   wsl --list --online
   

   This command will display a catalog of distributions (like Debian, Fedora, and OpenSUSE) available for installation.

2. To install a specific distribution, use:

   wsl --install -d <DistroName>
   

   Replace <DistroName> with the name of your chosen distribution (e.g., Debian). The installation process will begin, downloading and configuring the distribution for WSL.

Once installed, you can switch between distributions anytime. Simply launch your desired distro through the Start Menu or by opening a WSL terminal.

Enabling Additional Features

To fully unlock WSL’s potential, you’ll need to enable a couple of system features. These are required to support WSL’s virtualized environment and Linux kernel integration. Here’s how to do it:

1. Open PowerShell as an Administrator and run the following commands to enable the Virtual Machine Platform and Windows Subsystem for Linux:

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

2. Restart your computer after running these commands.

Alternatively, you can enable these features through the Windows GUI:

• Open the Control Panel and navigate to Programs > Turn Windows features on or off.
• Check the boxes for Virtual Machine Platform and Windows Subsystem for Linux, then click OK.

Enabling these features ensures WSL runs smoothly and supports advanced functionality. If you’re not sure whether they’re already enabled, running the above PowerShell commands won’t harm your system—it’ll simply notify you if the features are already active.

---

That’s all it takes to install and configure WSL. With your system prepped and ready, you can now enjoy the convenience of Linux tools integrated directly into your Windows environment.

Getting Started with Basic WSL Commands

Once you’ve installed WSL and chosen a Linux distribution, the next step is learning some essential commands. These will help you launch WSL, navigate the file system, manage Linux packages, and even access the internet directly from your terminal. Whether you’re a beginner or brushing up on the basics, mastering these commands is key to making the most out of WSL.

Launching and Accessing WSL

Launching WSL is simple and can be done in more than one way. The quickest and most common method is by running the wsl command in your terminal or command prompt. This starts WSL and brings you to the default Linux distribution you’ve installed.

• Open a Command Prompt, PowerShell, or Windows Terminal.
• Just type wsl and press Enter to launch your default Linux distro.

Want to open a specific Linux distribution? You can do that too. Each installed distro has a unique name, and you can use it to start the one you want. For example:

• To launch Ubuntu specifically, enter:

  wsl -d Ubuntu
  

You can also search for the installed distro by its name from the Start Menu and launch it directly. This is handy when you’re working with multiple distributions or need quick access to a particular one.

Navigating the Linux File System

Using WSL is just like working on a Linux machine, complete with the Linux file system. Commands like ls (list files) and cd (change directory) are your go-to tools when exploring files and directories.

Here’s a quick breakdown:

• List files in the current directory:

  ls
  

• Change to a specific directory:

  cd <directory_name>
  

  For example, to switch to your home directory, type cd ~.

What about accessing files on your Windows system? WSL makes it easy. All Windows drives can be accessed via the /mnt directory. For instance, the C drive is located at /mnt/c.

• To navigate to your Windows Documents folder, use:

  cd /mnt/c/Users/<YourUsername>/Documents
  

This level of interoperability between Linux and Windows is one of WSL’s most practical features. You can freely move and edit files across both systems without extra software.

Installing and Managing Linux Packages

Linux packages are the backbone of your system, and WSL allows you to install and manage them with ease. If you’re using a Debian-based distribution like Ubuntu, package management is done using apt.

Start by updating the package list to ensure you’re working with the latest versions:

• Update the package list:

  sudo apt update
  

Once the list is updated, you can upgrade all installed packages to their newest versions:

• Upgrade installed packages:

  sudo apt upgrade
  

To install a new software package, use the command sudo apt install, followed by the package name. For example, to install the git version control tool:

• Install a package:

  sudo apt install git
  

Want to clean up old or unnecessary files? Commands like sudo apt autoremove can tidy up your system by removing unused dependencies. Keeping your WSL instance updated and clean ensures better performance and reliability.

Accessing Network Resources

Your WSL terminal can also connect to the internet, making it a powerful tool for downloading files or troubleshooting network issues.

One of the simplest commands is ping, which you can use to test connectivity to a website or server. For example:

• Ping a website:

  ping google.com
  

If you need to fetch data or files from the web, Linux offers tools like curl and wget. Both are extremely versatile for sending requests or downloading files.

Here’s how to use them:

• Fetch a webpage with curl:

  curl https://example.com
  

• Download a file using wget:

  wget https://example.com/file.zip
  

These commands are ideal for tasks like downloading scripts or testing APIs, especially if you’re working with web development or system administration.

---

Mastering these basic WSL commands paves the way for a smooth and productive experience. With this foundational knowledge, you can now begin exploring WSL’s full potential. As you grow more comfortable, you’ll find there’s little you can’t do from your WSL terminal!

Advanced WSL Configurations for Power Users

WSL isn't just for beginners—it's a powerhouse for those who want to push the boundaries of Windows and Linux integration. With a little configuration, you can tweak WSL to perform faster, work smarter, and fit your workflows perfectly. In this section, we’ll explore some advanced settings and tips to use WSL like a pro.

Using WSL 2 and Upgrading from WSL 1

WSL has two different versions: WSL 1 and WSL 2. Understanding their differences is critical so you can choose the one that best suits your needs.

• WSL 1 uses a translation layer to map Linux calls to Windows. It’s lightweight, uses less memory, and has faster file access when working within the Windows file system. However, it doesn’t fully support all Linux kernel features.
• WSL 2, on the other hand, runs a real Linux kernel in a lightweight virtual machine. This offers full compatibility with Linux features, better performance in Linux-heavy operations, and improved networking capabilities. The trade-off? Slightly higher resource usage.

Want to upgrade to WSL 2? It’s a simple process. Start by checking your current version:

wsl --list --verbose

The output will show all installed distributions and their versions. To upgrade a specific distribution, use:

wsl --set-version <DistroName> 2

For example, to switch Ubuntu to WSL 2:

wsl --set-version Ubuntu 2

This command seamlessly upgrades the distro without losing existing data. Not sure which version to use? Go with WSL 2 for modern use cases like Docker or Kubernetes, as it’s optimized for those workflows.

Configuring WSL Settings

Fine-tuning WSL goes a long way in optimizing performance and usability. A few key settings can make all the difference.

Set a Default WSL Version

If you want all future installations to default to WSL 2, simply run:

wsl --set-default-version 2

This saves you from manually switching versions for every new distro you install.

Customize Resource Allocation with .wslconfig

For dedicated power users, updating the .wslconfig file in your Windows user directory (C:\Users\<YourUsername>\.wslconfig) gives you direct control over WSL’s resource allocation:

[wsl2]
memory=4GB   # Limit memory usage
processors=2 # Limit CPU cores
swap=2GB     # Set swap file size
localhostForwarding=true # Enable localhost network access

If you’re noticing high memory or CPU usage on your system, adjusted limits here can help. After saving the file, restart WSL with:

wsl --shutdown

WSL dynamically uses resources, but these caps ensure your Windows system stays responsive even during heavy Linux workloads.

Integrating WSL with Visual Studio Code

Looking to streamline your development environment? Combine the power of WSL with Visual Studio Code to make coding and debugging a breeze.

Start by installing the Remote - WSL extension in VS Code:

1. Open VS Code and go to the Extensions pane.
2. Search for “Remote - WSL” and click Install.

Once installed, you can open any directory inside your WSL distro directly from VS Code. Just type the following in your terminal:

code .

This command opens the current working directory in VS Code, using the Linux environment under the hood. You get the best of both worlds—Linux tools and workflows paired with a modern editor like VS Code.

Benefits include:

• Seamless file editing between Windows and WSL.
• Integrated terminals that reflect your chosen distro’s environment.
• Debugging support for languages like Python, Node.js, and C++ in WSL.

It’s especially useful for cross-platform development and working with containerized apps.

Automating Tasks with Bash Scripts

Automation is where Linux truly shines, and WSL lets you bring that power to Windows. By writing Bash scripts, you can automate repetitive tasks, saving time and effort.

Here’s an example: Imagine you need to back up a specific directory daily. Create a Bash script like this:

1. Open your WSL terminal and create a new file:

nano backup.sh

2. Add the following script:

#!/bin/bash

SOURCE_DIR="/mnt/c/Users/<YourUsername>/Documents"
BACKUP_DIR="/mnt/c/Users/<YourUsername>/Backups"

# Create backup directory if it doesn’t exist
mkdir -p $BACKUP_DIR

# Copy files
cp -r $SOURCE_DIR $BACKUP_DIR
echo "Backup completed on $(date)"

3. Save and exit (CTRL+O, Enter, then CTRL+X).

4. Make the file executable:

chmod +x backup.sh

5. Run it:

./backup.sh

For automation, you can schedule this script through Windows Task Scheduler or the Linux cron service within WSL. On Windows, create a Task Scheduler entry that runs:

wsl /path/to/backup.sh

This example scratches the surface—scripts can handle everything from server deployments to routine file cleanups. Once you start automating tasks, you'll wonder how you ever managed without it.

---

With these advanced configurations, WSL becomes a robust tool tailored to your specific needs. From upgrading to WSL 2 to scripting complex tasks, the possibilities are nearly endless. Push your setup further, and it will pay off in speed, efficiency, and flexibility.

Troubleshooting and Common Issues

When using WSL, it’s not uncommon to encounter hiccups along the way. Whether you're facing installation errors, networking problems, or issues with a corrupted Linux distribution, these types of problems can stop your workflow in its tracks. The good news? Most of these are easy to resolve with the right approach. Here’s how to tackle some common WSL-related issues.

Fixing Installation Errors

Sometimes, the installation of WSL doesn't go as smoothly as planned. One of the most reported issues is a missing kernel update, especially when installing WSL 2. This can happen if your system isn’t fully updated or lacks specific configurations.

Here’s how to fix it:

1. Check Windows Updates
   Ensure your Windows system is completely up to date. Open the Start Menu, type Windows Update, and select Check for updates. If there are pending updates, install them and restart your computer.

2. Use the WSL Kernel Update Package
   If your system prompts you with an error like "WslRegisterDistribution failed with error: 0x80370102," it’s likely due to a missing WSL 2 kernel update. Download and install the latest Linux kernel update from the Microsoft WSL website.

3. Enable Required Features
   Confirm that WSL and Virtual Machine Platform features are enabled. Open a PowerShell terminal as an administrator and run:

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

   Restart your computer afterward, then try installing again.

4. Run the Windows Update Assistant
   If you’re still having trouble, you might be running a version of Windows that’s too old for WSL 2. Use the Windows Update Assistant to ensure you're on the latest supported version of Windows 10 or 11.

These steps usually resolve installation-related issues. If you’re still stuck, double-check that your system meets the hardware requirements for virtualization.

Resolving Networking Problems

Networking issues in WSL can range from DNS resolution errors to a complete inability to connect to the internet. Although WSL is designed to share your Windows network adapter, things can occasionally go wrong.

Here are a few solutions you can try:

• Check Your Firewall Settings
  Sometimes a firewall rule can block WSL’s network access. To fix this, open your firewall settings (type Windows Defender Firewall into the Start Menu) and ensure WSL or its Linux distro has network permissions. You can also temporarily disable your firewall to test if it’s the cause.

• Reset WSL’s Network Configurations
  If things seem misconfigured, resetting WSL’s network adapter often solves the problem. Open PowerShell as an administrator and input:

  netsh winsock reset
  

  Follow this by restarting your system.

• Manually Set a DNS Server
  When DNS isn’t working correctly inside WSL, you can manually specify a DNS server. Edit the /etc/resolv.conf file in your Linux distribution using:

  sudo nano /etc/resolv.conf
  

  Add a line like this:

  nameserver 8.8.8.8
  

  Save the changes and restart the distro by closing and reopening the terminal.

• Ensure Windows Internet Works
  Since WSL relies on your Windows network, issues on the Windows side will carry over. Make sure your internet connection is stable on the Windows host before troubleshooting within WSL.

These action steps should restore your WSL network connection in most cases. If all else fails, consider updating to a newer version of WSL or reinstalling your distribution.

Repairing a Corrupted Linux Distribution

Occasionally, a Linux distribution in WSL may become corrupted due to incomplete updates, misconfigurations, or other anomalies. If this happens, you might notice strange errors or the distro failing to launch altogether.

Here’s what you can do:

1. Backup Important Files
   Before diving into repairs, check if you can still access your files. If possible, back them up first. You can access the Linux file system through the terminal or use File Explorer (\\wsl$\<DistroName>).

2. Restart the Distro Process
   Sometimes, simply restarting the WSL process fixes temporary glitches. Run:

   wsl --shutdown
   

3. Revert to Default Configurations
   If you’ve recently altered your distro’s configuration files (like .bashrc or .profile), revert those changes. Use a text editor like nano to restore default settings.

4. Unregister and Reinstall the Distro
   If the corruption persists, it’s often faster to unregister and reinstall the distribution. Open PowerShell and enter:

   wsl --unregister <DistroName>
   

   For example, to remove Ubuntu:

   wsl --unregister Ubuntu
   

   This unregisters (completely deletes) the distro from WSL. Afterward, reinstall the distribution by downloading it again from the Microsoft Store.

5. Use the --import Command (Optional Advanced)
   For advanced users, you can export and import distributions to migrate or manually repair distro configurations. Export your distro first:

   wsl --export <DistroName> <BackupLocation>.tar
   

   Later, re-import the backup with:

   wsl --import <NewDistroName> <InstallLocation> <BackupLocation>.tar
   

When reinstalling, always double-check your configuration and package manager settings to avoid repeating errors that led to the corruption.

---

By following these troubleshooting steps, you can quickly fix common problems in WSL and get back on track. Whether it’s an installation hiccup, a network snag, or a corrupted distro, resolving these issues doesn’t have to leave you stuck.