---
title: "WSL"
description: "Install Ubuntu on WSL 2, create your Linux user, and tune memory, networking and systemd for web development."
canonical_url: "https://vinicunca.dev/windows-dev/guide/wsl"
---
# WSL

> Install Ubuntu on WSL 2, create your Linux user, and tune memory, networking and systemd for web development.

The Windows Subsystem for Linux (WSL) runs a real Linux kernel in a lightweight virtual machine, so you can use Linux tools, shells and package managers without dual-booting. Everything after this step (zsh, Git, Node.js, pnpm and your projects) lives inside this Linux distribution.

This guide uses Ubuntu, the default. You can install other distributions side by side at any time.

## Install

### Run the installer

Open **Terminal (Admin)** (see [Package Managers](https://vinicunca.dev/windows-dev/guide/package-managers#open-an-administrator-shell)) and run:

```powershell
wsl --install
```

This enables the required Windows features, installs the latest WSL and Linux kernel, sets WSL 2 as the default version and installs Ubuntu.

### Restart Windows

Reboot when prompted. After signing back in, Ubuntu finishes installing in a terminal window.

### Create your Linux user

Enter a username and password when asked. Nothing is shown while you type the password; that's expected.

- This account is separate from your Windows account and belongs to this distribution only.
- It's the default user and can run administrative commands with `sudo`.
- You'll create a new one whenever you install, reinstall or reset a distribution.

### Update Ubuntu

Windows doesn't update the packages inside your distribution, so do it now and then:

```bash
sudo apt update && sudo apt upgrade -y
```

> [!TIP]
> 
> If WSL is already installed, `wsl --install` without arguments may only print help. Install a specific distribution instead:
> 
> ```powershell
> # See which distributions are available
> wsl --list --online
> 
> # Install one by name
> wsl --install -d Ubuntu-24.04
> ```

## Useful commands

Run these from PowerShell:

```powershell
# Update WSL itself (installed from the Microsoft Store)
wsl --update

# Show the WSL version and kernel version
wsl --version

# List installed distributions and their WSL version
wsl --list --verbose

# Choose which distribution `wsl` opens by default
wsl --set-default Ubuntu

# Stop all distributions and the WSL virtual machine
wsl --shutdown
```

See the [WSL command reference](https://learn.microsoft.com/en-us/windows/wsl/basic-commands) for the rest.

## Configure WSL

WSL has two configuration files. Changes take effect after you run `wsl --shutdown` and open a new WSL tab.

### Global settings: `.wslconfig`

`%UserProfile%\.wslconfig` (for example `C:\Users\you\.wslconfig`) configures the virtual machine shared by all distributions. It doesn't exist by default, so create it with any text editor, for example `notepad $env:USERPROFILE\.wslconfig` from PowerShell.

```ini [.wslconfig]
[wsl2]
# Cap the RAM WSL can use (default: 50% of Windows memory)
memory=8GB

# Share Windows' network interfaces: localhost works both ways,
# and IPv6 and VPNs behave like they do on Windows
networkingMode=mirrored
```

> [!NOTE]
> 
> Mirrored networking requires Windows 11 version 22H2 or later. On older builds, leave `networkingMode` out; the default NAT mode still forwards `localhost` ports from WSL to Windows, so dev servers open in your Windows browser either way.

Pick a `memory` value that leaves enough RAM for Windows, your browser and your editor. All available keys are listed in the [WSL settings reference](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#configuration-settings-for-wslconfig). The **WSL Settings** app, installed with WSL, edits the same file through a UI.

### Per-distribution settings: `/etc/wsl.conf`

`/etc/wsl.conf` lives inside the distribution. Make sure systemd is enabled so services such as Docker, `snap` and `systemctl` work like they do on a regular Linux machine. The Ubuntu image installed by `wsl --install` already enables it; other distributions may not. Check with `cat /etc/wsl.conf`, and if the setting is missing, add it:

```bash
sudo nano /etc/wsl.conf
```

```ini [/etc/wsl.conf]
[boot]
systemd=true
```

After restarting WSL, confirm systemd is running:

```bash
systemctl list-unit-files --type=service
```

## Files and performance

Keep your projects in the Linux file system, for example `~/code`, not under `/mnt/c`.

> [!WARNING]
> 
> Tools running in WSL are much slower on files under `/mnt/c` (your Windows drives), and file watchers used by Vite and Nuxt may miss changes there. Clone repositories inside your Linux home directory.

```bash
mkdir -p ~/code
cd ~/code
```

You can still reach files in both directions:

- **From Windows**, File Explorer shows a **Linux** entry in the navigation pane with every distribution. You can also type `\\wsl.localhost\Ubuntu\home\<your-user>` in the address bar. Right-click your `code` folder and select **Pin to Quick access** for one-click access.
- **From WSL**, run `explorer.exe .` to open the current Linux directory in File Explorer. Your Windows drives are mounted under `/mnt`, so your Windows user folder is `/mnt/c/Users/<you>`.

![File Explorer with a pinned code directory inside WSL](https://vinicunca.dev/images/code-dir.jpg)

## Set Windows Terminal to open Ubuntu

Now that Ubuntu exists, go back to [Windows Terminal](https://vinicunca.dev/windows-dev/guide/terminal#open-wsl-by-default) and make it the default profile with `~` as the starting directory.

If WSL ever stops responding, see [Troubleshooting](https://vinicunca.dev/windows-dev/extras/troubleshooting).

---

- [Docs](https://learn.microsoft.com/en-us/windows/wsl/)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.