How to Set Up Windows Subsystem for Linux (WSL) for Development – A Beginner’s Guide

Windows Subsystem for Linux (WSL) has become the go‑to solution for developers who want the power of a Linux terminal without leaving the comfort of Windows. Whether you’re building web apps, scripting automation, or just experimenting with Bash, WSL gives you a native‑like Linux experience on a Windows 10 or 11 machine. This guide walks you through the entire setup process—from enabling the feature to installing your favorite tools—so you can start coding in minutes.

What You’ll Need

• A Windows 10 (version 2004 or later) or Windows 11 PC
• Administrative privileges on the machine
• An internet connection for downloading packages
• Basic familiarity with the command line (no prior Linux experience required)
• Optional: A Microsoft Store account if you prefer installing a distro from the Store

Step 1: Enable the WSL Feature

WSL is not turned on by default. Open PowerShell as an administrator (right‑click the Start button → Windows PowerShell (Admin)) and run the following command:

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

This command tells Windows to install the core WSL subsystem. You’ll also want to enable the Virtual Machine Platform, which is required for WSL 2 (the newer, faster architecture):

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

After both commands finish, restart your computer. A reboot is essential; otherwise the new kernel won’t load.

Step 2: Set WSL 2 as the Default Version

WSL 2 runs a real Linux kernel inside a lightweight VM, giving you near‑native file system performance and full system‑call compatibility. To make sure any new distro you install uses WSL 2, execute:

wsl --set-default-version 2

If you see an error about the kernel version, you’ll need to download the latest WSL 2 kernel package from Microsoft’s website (https://aka.ms/wsl2kernel) and run the installer.

Step 3: Choose and Install a Linux Distribution

Microsoft Store offers several official distros—Ubuntu, Debian, Kali, openSUSE, and more. For beginners, Ubuntu LTS is the safest bet. Open the Microsoft Store, search for “Ubuntu”, and click “Get”. Alternatively, you can install via the command line:

wsl --install -d Ubuntu

This single command does three things: it enables WSL (if you missed Step 1), sets WSL 2 as default, and pulls the latest Ubuntu image. After installation, launch Ubuntu from the Start menu. The first launch will ask you to create a Unix username and password—choose something you’ll remember, as this will be your default non‑root user.

Step 4: Configure the Terminal Experience

While the default Windows console works, many developers prefer Windows Terminal for its tabbed interface, custom themes, and split‑pane support. Download it from the Microsoft Store, then add a new profile for your Linux distro:

1. Open Windows Terminal → Settings (Ctrl+,).
2. Under “Profiles”, click “Add new” and select your installed distro.
3. Give it a friendly name (e.g., “Ubuntu‑WSL”) and choose a color scheme.

Now you can open multiple tabs—one for PowerShell, another for Ubuntu—side by side. If you want your Linux home directory to open in the Windows file explorer, enable the “Open in Windows Explorer” option in the profile settings.

Step 5: Install Core Development Tools

With your Linux terminal ready, it’s time to add the tools you’ll actually use for coding. Below is a quick starter pack for web development, but feel free to adjust based on your stack.

# Update package lists and upgrade existing packages
sudo apt update && sudo apt upgrade -y

# Install Git, curl, and build essentials (gcc, make, etc.)
sudo apt install -y git curl build-essential

# Install Node.js (using NodeSource for the latest LTS)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Install Python 3 and pip
sudo apt install -y python3 python3-pip

# Optional: Install Docker CLI (requires Docker Desktop on Windows)
sudo apt install -y docker.io
sudo usermod -aG docker $USER
newgrp docker   # refresh group membership without logout

After the installations, verify each tool:

git --version
node -v
npm -v
python3 --version
docker --version   # should show the client version

If any command fails, double‑check your internet connection and run sudo apt update again.

Step 6: Bridge Windows and Linux Filesystems

One of the biggest advantages of WSL is seamless file sharing. Windows drives are mounted under /mnt (e.g., /mnt/c for C:). To edit code in VS Code, install the Remote – WSL extension:

# In Windows PowerShell
code --install-extension ms-vscode-remote.remote-wsl

Then open a folder from your Linux distro directly in VS Code:

code .   # runs inside the Ubuntu terminal

VS Code will launch a new window connected to WSL, giving you full IntelliSense, debugging, and terminal access—all without leaving the editor.

Step 7: Keep Your Environment Updated

WSL receives regular updates from Microsoft, and Linux packages need routine upgrades. Set a weekly reminder to run:

sudo apt update && sudo apt full-upgrade -y
wsl --update   # updates the WSL kernel and components

For major distro upgrades (e.g., Ubuntu 20.04 → 22.04), use the built‑in release‑upgrade tool:

sudo do-release-upgrade

Always back up important projects before a major upgrade, or clone them to a separate Windows folder.

Common Mistakes to Avoid

1. Skipping the reboot after enabling WSL. Without a restart, the kernel won’t load and you’ll see cryptic “WSL not installed” errors.

2. Installing a distro but leaving it on WSL 1. WSL 1 lacks full system‑call support, which can break Docker, Kubernetes, or newer language runtimes. Always verify with wsl -l -v and set the version to 2 if needed.

3. Editing Linux files from Windows Explorer. While possible, it can corrupt permissions and cause slow performance. Prefer editing inside the Linux filesystem (/home/username) or use VS Code’s Remote‑WSL extension.

4. Running sudo inside a non‑default user. If you created a separate user for a project, remember to prepend sudo for system‑wide changes; otherwise you’ll get “permission denied”.

5. Forgetting to add your user to the docker group. Without this, every Docker command will require sudo, which defeats the purpose of a smooth dev workflow.

Tips and Tricks

• Alias common commands. Add alias ll='ls -la' to ~/.bashrc for a quicker directory listing.

• Use .wslconfig for resource limits. Create C:UsersYourName.wslconfig with:

[wsl2]
memory=4GB   # limit RAM
processors=2 # limit CPU cores

• Mount external drives. Run sudo mkdir /mnt/e && sudo mount -t drvfs E: /mnt/e to access an external USB stick.

• Sync environment variables. Add export PATH=$PATH:/mnt/c/Program Files/Nodejs to ~/.profile if you need Windows tools inside Linux.

• Backup your distro. Export a snapshot with wsl --export Ubuntu ubuntu-backup.tar and restore later with wsl --import UbuntuRestored C:WSLUbuntuRestored ubuntu-backup.tar.

Frequently Asked Questions

Can I run graphical Linux apps on WSL?

Yes. Starting with Windows 10 build 21364, WSL supports GUI apps out of the box. Install the wslg package (usually pre‑installed) and launch a GUI program like gedit &. The window will appear on your Windows desktop.

Do I need to reinstall my distro after a Windows update?

No. Windows updates rarely affect WSL installations. However, major feature updates may require you to run wsl --update and restart the WSL service (wsl --shutdown) to pick up the new kernel.

Is WSL secure for production workloads?

WSL is designed for development and testing, not for hosting production services. While it runs a real Linux kernel, it shares the Windows kernel’s security surface. For production, use a dedicated VM or physical Linux server.

Conclusion

Setting up Windows Subsystem for Linux is a straightforward process that unlocks a full Linux development environment on a Windows machine. By following the steps above—enabling the feature, installing a distro, configuring your terminal, and adding essential tools—you’ll have a powerful, flexible workspace ready for anything from web development to data science. Keep your system updated, avoid the common pitfalls, and you’ll enjoy a smooth, integrated workflow that bridges the best of both worlds.

Photo by Sandisk on Unsplash