Setting Up WSL2 on Windows

WSL (Windows Subsystem for Linux) lets you run a Linux environment directly on Windows - no VM, no dual boot. WSL2 runs a real Linux kernel in a lightweight managed VM, giving you full syscall compatibility and much better performance than WSL1.

Prerequisites

• Windows 10 version 2004+ or Windows 11
• Admin access to your machine
• PowerShell or Windows Terminal

Install WSL

From an elevated PowerShell or Command Prompt:

wsl --install

This installs WSL2 and Ubuntu (the default distro) in one step. Restart when prompted.

To install a different distro, list what’s available first:

wsl --list --online

Then install by name:

wsl --install -d Debian

To check what’s installed and running:

wsl --list --verbose

First run

Launch the distro from the Start menu or by typing its name in a terminal. The first launch prompts you to create a UNIX username and password - this is local to the distro and doesn’t need to match your Windows credentials.

Set WSL2 as the default version if it isn’t already:

wsl --set-default-version 2

Update the distro

After first launch, update the package list and upgrade installed packages:

sudo apt update && sudo apt upgrade -y

Install any essentials you need:

sudo apt install -y curl git build-essential unzip

Configuration

WSL has two config files that control different things.

.wslconfig - Windows-side limits

Controls resources WSL2 allocates from Windows. Create or edit C:\Users\<your-username>\.wslconfig:

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

By default WSL2 can use up to 50% of system RAM and all CPU cores. On a machine shared with other workloads, it’s worth capping this.

After editing, restart WSL for changes to take effect:

wsl --shutdown

wsl.conf - distro-side settings

Controls behaviour inside the distro. Create or edit /etc/wsl.conf inside WSL:

sudo nano /etc/wsl.conf

Useful options:

[boot]
systemd=true

[automount]
enabled=true
options="metadata"

[network]
hostname=my-dev-box
generateResolvConf=true

[user]
default=myusername

• systemd=true - enables systemd, needed for Docker Engine, services, etc.
• automount options="metadata" - lets you set Linux file permissions on Windows-mounted drives
• hostname - sets the hostname inside WSL (useful to distinguish from the Windows host)
• user.default - the user WSL drops you into on launch

Restart WSL after saving:

wsl --shutdown

Useful WSL commands

# List installed distros and their state
wsl --list --verbose

# Stop all running distros
wsl --shutdown

# Stop a specific distro
wsl --terminate Ubuntu

# Set a different distro as default
wsl --set-default Debian

# Run a command directly without entering the shell
wsl ls -la /home/myusername

# Export a distro to a backup file
wsl --export Ubuntu ubuntu-backup.tar

# Import from backup
wsl --import Ubuntu C:\WSL\Ubuntu ubuntu-backup.tar --version 2

Corporate proxy

If you’re on a corporate network, WSL2’s outbound connections go through a virtual network adapter that often doesn’t inherit Windows proxy settings. Here’s what to configure.

Shell environment

1. Open ~/.bashrc (or ~/.zshrc if you use zsh):

nano ~/.bashrc

2. Add the proxy variables:

export HTTP_PROXY="http://proxy.your-company.com:8080"
export HTTPS_PROXY="http://proxy.your-company.com:8080"
export NO_PROXY="localhost,127.0.0.1,169.254.0.0/16,10.0.0.0/8"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

3. Reload the shell:

source ~/.bashrc

apt

1. Create /etc/apt/apt.conf.d/proxy.conf:

sudo nano /etc/apt/apt.conf.d/proxy.conf

2. Add the proxy config:

Acquire::http::Proxy "http://proxy.your-company.com:8080";
Acquire::https::Proxy "http://proxy.your-company.com:8080";

3. Test:

sudo apt update

curl and wget

curl and wget pick up HTTP_PROXY/HTTPS_PROXY from the environment automatically once the shell variables are set above. No extra config needed.

git

git config --global http.proxy http://proxy.your-company.com:8080
git config --global https.proxy http://proxy.your-company.com:8080

To unset if you move off the corporate network:

git config --global --unset http.proxy
git config --global --unset https.proxy

Keeping WSL updated

The WSL platform itself (separate from the distro) updates via Windows Update or manually:

wsl --update

The distro packages update via apt inside WSL as usual. There’s no automatic update mechanism for the distro - run sudo apt update && sudo apt upgrade periodically.

Notes