🐧 How to install Linux on Windows with WSL

tool

The Windows Subsystem for Linux (WSL) lets developers install a Linux distribution (such as Ubuntu, OpenSUSE, Kali, Debian, Arch Linux, etc) and use Linux applications, utilities, and Bash command-line tools directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.

What is WSL?

WSL (Windows Subsystem for Linux) is a compatibility layer for running Linux binary executables natively on Windows. It allows developers to use Linux tools, shells, and applications directly within Windows, without the need for a full virtual machine or dual-boot setup. WSL 2 uses a lightweight virtual machine for improved performance and compatibility, supporting full Linux kernel features, better system call compatibility, and faster file system performance compared to WSL 1.

Install WSL Command

Open PowerShell or Windows Command Prompt as Administrator, then run:

powershell
wsl --install

This command installs WSL 2 and the default Linux distribution (usually Ubuntu LTS).

To see available distributions and install a specific one:

powershell
wsl --list --online           # List available distributions
wsl --install -d <DistroName> # Replace <DistroName> with your choice, e.g., Ubuntu-22.04

After installation, restart your computer if prompted.

Tip: You can upgrade from WSL 1 to WSL 2 with wsl --set-version <DistroName> 2.

Initial Setup and User Management

When you launch your new Linux distribution for the first time, you'll be prompted to create a user and password. If you want to add additional users later:

WSL
sudo adduser <username>
sudo usermod -aG sudo <username> # Add user to sudoers group

Switch to the new user:

WSL
su - <username>

Tip: You can set the default user for your distro with wsl -d <DistroName> -u <username>.

Install Visual Studio Code

Download Visual Studio Code and install it on Windows.

To use VS Code with WSL, install the Remote - WSL extension. This allows you to open and develop inside your WSL environment directly from VS Code, with full access to Linux tools and files.

Use Windows Proxy in WSL2

Note: Ubuntu version should be at least 22.04 for best compatibility.

To enable mirrored networking (useful for proxy and network access):

  1. In your Windows home directory (%UserProfile%, typically C:\Users\<UserName>), create a .wslconfig file:

    [wsl2]
networkingMode=mirrored

  2. After saving, restart WSL:

    powershell
    wsl --shutdown

    Then relaunch your terminal.

If you use Clash Verge for proxy, System Proxy for apt update and apt upgrade, TUN mode for hotspot sharing. Note: network hotspot sharing only works in GVisor mode.

Install zsh and oh-my-zsh

WSL
sudo apt update
sudo apt install zsh
# Make zsh the default shell for your user (do NOT use sudo)
chsh -s $(which zsh)

  1. Install oh-my-zsh for a better shell experience:

    WSL
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

  2. Change theme or customize plugins as desired.

Install Homebrew (Linuxbrew)

Homebrew on Linux is a popular package manager. Install it with:

WSL
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, follow the instructions to add Homebrew to your shell profile (e.g., add eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" to your .zshrc or .bashrc).

Useful WSL Commands

WSL
explorer.exe .       # Open current folder in Windows Explorer
wsl.exe hostname -I  # Get the WSL2 IP address
wsl.exe --update     # Update WSL to the latest version
wsl.exe --status     # Show WSL configuration and version info
wsl.exe --shutdown   # Restart WSL (helpful for networking issues)

Configure Port Forwarding to Access WSL2 from the Local Network

By default, WSL2 runs in a virtualized network, so services (e.g., web servers) are not accessible from other devices on your LAN. To expose a port:

Run the following commands in PowerShell (Admin).

  1. Enable port forwarding from Windows to WSL2:

    powershell
    netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=<PORT> connectaddress=<WSL2_IP> connectport=<PORT>
# Example for port 4000 to 3000:
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=4000 connectaddress=localhost connectport=3000

  2. Allow the port in Windows Firewall:

    powershell
    New-NetFirewallRule -DisplayName "Allow_TCP_<PORT>" -Direction Inbound -LocalPort <PORT> -Protocol TCP -Action Allow
# Example for port 4000:
New-NetFirewallRule -DisplayName "Allow_TCP_4000" -Direction Inbound -LocalPort 4000 -Protocol TCP -Action Allow

  3. Verify forwarding:

    powershell
    netsh interface portproxy show all

  4. Delete an unwanted forwarding rule:

    powershell
    netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=<PORT>

Note: If your app can bind to address 0.0.0.0, you don't need portproxy—just add the firewall rule and access the service directly via your Windows host's IP.

Tip: To check your WSL2 IP address, run hostname -I inside WSL.

Additional Tips

Terminal Configurations

  • Size: 72 x 20
  • Theme: Campbell (or your preference)
  • Opacity: 95%

File System Interoperability

  • Access Windows files from WSL at /mnt/c/Users/<UserName>/
  • Access WSL files from Windows at \\wsl$\Ubuntu-22.04\home\<username>\
  • You can drag and drop files between Windows Explorer and your WSL home directory.

Updating and Upgrading

Keep your Linux environment up to date:

WSL
sudo apt update && sudo apt upgrade

Running GUI Linux Apps

Recent WSL2 versions support running Linux GUI apps natively (via WSLg). Just install your favorite Linux GUI app and launch it from the WSL terminal.

Troubleshooting

  • If you encounter networking issues, try restarting WSL: wsl --shutdown
  • For GUI apps, install WSLg (included by default in recent WSL2).
  • For more advanced networking, see WSL Networking Docs.
  • If you have DNS or proxy issues, try editing /etc/resolv.conf or resetting your .wslconfig.

References