Setting Up WSL on Windows: A Practical Guide

WSL let me keep a Linux development environment without leaving Windows for everyday applications.

During university, I moved to Linux because Windows setup often differed from the programming tutorials I followed. I later used a dual-boot setup: Linux for development and Windows for other software.

Switching systems became inconvenient when meetings and other Windows applications were part of my day. WSL 2 gave me another option: keep the Linux tools and use Windows applications alongside them.

This guide uses Ubuntu on WSL 2. Run Windows commands in PowerShell and Linux commands inside Ubuntu. Distribution names and package versions depend on your installation.

1. Install WSL and Ubuntu

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu

Restart Windows when prompted. Launch Ubuntu and create your Linux username and password.

The one-command method covers Windows 11 and eligible Windows 10 builds. Use Microsoft's installation guide for prerequisites and the manual fallback.

If WSL is already installed, list available distributions before installing another:

wsl --list --online

2. Check the installed versions

In PowerShell, inspect WSL and its distributions:

wsl --version
wsl --list --verbose

The second command reports whether each distribution uses WSL 1 or WSL 2. For an existing WSL 1 installation, follow Microsoft's conversion instructions.

Inside Ubuntu, check the distribution release:

cat /etc/os-release

Record these versions when reporting a setup problem. “Ubuntu on WSL” alone leaves several variables unknown.

3. Install the development tools

Inside Ubuntu, refresh the package lists and review available upgrades:

sudo apt update
sudo apt upgrade

Install the basic compiler tools, Git, curl, and unzip:

sudo apt install build-essential git curl unzip

Add project-specific runtimes separately. This keeps the base setup small and makes required versions explicit.

4. Keep Linux projects in the Linux filesystem

Create a workspace inside your Linux home directory:

mkdir -p ~/projects
cd ~/projects

The important distinction is the filesystem boundary, rather than the Windows drive letter. Linux tools generally perform better with files in the WSL filesystem than with files under mounted Windows paths such as /mnt/c.

Microsoft documents this in its filesystem guidance. It applies to mounted D: and E: drives too. C: has no special performance guarantee.

From a Linux project directory, open Windows File Explorer with:

explorer.exe .

5. Open the project in VS Code

Install VS Code on Windows and add Microsoft's WSL extension.

From your project directory inside Ubuntu, run:

code .

Check that VS Code shows a WSL connection before installing project dependencies. Its integrated terminal should open in the Linux environment.

6. Set resource limits only when needed

WSL 2 supports resource settings in %UserProfile%.wslconfig on Windows. For example:

[wsl2]
memory=4GB
processors=2
swap=2GB

These are example limits, not requirements. Choose values that fit your machine and workload. See the configuration reference for supported options.

Save your Linux work before applying the settings. This PowerShell command stops running distributions:

wsl --shutdown

Launch Ubuntu again after the shutdown.

Where to go next

The useful result is a Linux workspace that fits your Windows workflow. Keep source files in Linux, record tool versions, and add only the services your project needs.

For a local database, continue with PostgreSQL on WSL.