Setting Up WSL 2 for Software Development on Windows

Windows Subsystem for Linux (WSL) lets developers run a real Linux distribution such as Ubuntu directly on Windows, without dual booting or managing a separate virtual machine. For teams whose applications run on Linux servers, it means developing in the same environment as production while keeping Windows for everything else. Installation takes one command, but a few choices made in the first hour, especially where project files live and how much memory WSL may use, decide whether the setup feels fast or frustrating.

WSL 1 and WSL 2

WSL 2 runs a real Linux kernel inside a lightweight virtual machine that Windows manages for you. WSL 1 translated Linux system calls into Windows calls instead. New installations use WSL 2 by default, and for development it is the right choice in almost every case.

Installing WSL

WSL requires Windows 10 version 2004 (build 19041) or later, or Windows 11. Open PowerShell as administrator, run wsl --install, and restart the computer. The command enables the required Windows features and installs Ubuntu. On first launch, Ubuntu asks for a Linux username and password, which are separate from your Windows account.

• wsl --list --online shows the distributions available to install, and wsl --install -d Debian installs a specific one.
• wsl --list --verbose (or wsl -l -v) shows the installed distributions and whether each one runs on WSL 1 or WSL 2.
• wsl --set-version Ubuntu 2 converts an older WSL 1 distribution to WSL 2.
• wsl --update updates WSL itself, and sudo apt update followed by sudo apt upgrade updates the packages inside Ubuntu.

Keep Project Files in the Linux File System

This is the most common cause of a slow WSL setup. Windows drives are available inside WSL under /mnt/c, but every file operation there crosses the boundary between the two systems. Commands such as npm install, composer install, git status, or a large build can be many times slower than the same commands on files stored inside Linux. Microsoft's own guidance is to keep files in the Linux file system when working from a Linux command line.

Clone repositories into your Linux home directory, for example /home/username/projects. You can still open these files from Windows: run explorer.exe . in a WSL terminal to open the current folder in File Explorer, or type \\wsl$ in the Explorer address bar to browse every installed distribution. File watchers used for hot reload in tools such as Vite, Next.js, and Laravel Mix also tend to work far more reliably when the files live on the Linux side.

Quick check: run pwd in the terminal where you work on your project. If the path starts with /mnt/c, move the project into your Linux home directory before tuning anything else.

Editor and Git

With the WSL extension for Visual Studio Code, running code . in a WSL terminal opens the folder in VS Code on Windows while extensions, terminals, and debuggers run inside Linux. Language servers and linters then see the same paths and tool versions as your build. JetBrains IDEs also support projects and toolchains inside WSL.

• Install and run Git inside WSL for projects stored in Linux, instead of mixing Git for Windows and Linux Git on the same repository.
• Set your name and email again inside WSL, because Linux Git has its own configuration.
• Add a .gitattributes file with consistent line endings, such as * text=auto eol=lf, so files do not change just because someone edited them on Windows.
• Create SSH keys inside WSL for GitHub or GitLab, or configure Git to use Git Credential Manager from Git for Windows so credentials are shared.

Limit Memory and CPU with .wslconfig

By default, the WSL 2 virtual machine may use up to half of the computer's memory, plus swap equal to a quarter of it. On a laptop with 16 GB of RAM, a busy Docker setup inside WSL can leave Windows short of memory for the browser and IDE. Create a file named .wslconfig in your Windows user folder (C:\Users\username) with a [wsl2] section and lines such as memory=6GB, processors=4, and swap=4GB, adjusted to your hardware. Recent versions also offer a WSL Settings app in the Start menu for the same options.

Changes only apply after the WSL virtual machine stops completely. Run wsl --shutdown from PowerShell, wait a few seconds, then open the terminal again.

Docker and systemd

There are two common ways to run containers. Docker Desktop with the WSL 2 backend is the simplest and integrates with Windows, but its licence requires a paid subscription for larger companies, currently those with more than 250 employees or more than 10 million US dollars in annual revenue. The alternative is to install Docker Engine directly inside the Linux distribution, which works like it does on a Linux server.

Docker Engine and many other services expect systemd. Recent Ubuntu images on WSL usually enable it already. If not, add a [boot] section with systemd=true to /etc/wsl.conf inside the distribution, then run wsl --shutdown and start it again.

Networking and Accessing Your Application

A development server started inside WSL, for example on port 3000, can be opened from a Windows browser at localhost:3000 because WSL forwards localhost by default. Problems tend to appear with corporate VPNs, proxies, or when other devices on the network need to reach the application. On Windows 11 version 22H2 or later, setting networkingMode=mirrored in .wslconfig makes WSL share the Windows network interfaces, which resolves many of these cases.

Backups and Disk Space

• Your Linux files live inside a virtual disk file. If the distribution is unregistered, that disk is deleted, so keep work in Git and back up anything else.
• wsl --export Ubuntu D:\backup\ubuntu.tar saves the whole distribution to a file, and wsl --import restores it, which is also a simple way to move the setup to a new laptop.
• The virtual disk grows as you add files but does not always shrink automatically after you delete them. Clean up old Docker images and caches regularly.

Common Problems and Fixes

A Setup Checklist for a New Developer Laptop

1. 1Run wsl --install as administrator, restart, and create the Linux user.
2. 2Update WSL and the distribution packages, and enable systemd if the distribution does not have it yet.
3. 3Create .wslconfig with memory and CPU limits that leave enough room for Windows.
4. 4Install Git, set your name and email, add SSH keys, and clone projects into the Linux home directory.
5. 5Install VS Code with the WSL extension, then open projects with code . from the WSL terminal.
6. 6Install the language runtimes and Docker your projects need inside Linux, and export the distribution once everything works as a ready-made backup.