WSL2: Linux on Windows for Developers Guide (2026)

Q: What is WSL2 and how is it different from WSL1?

WSL2 runs a real Linux kernel inside a lightweight Hyper-V utility VM, while WSL1 translated Linux syscalls through a compatibility layer. For PHP, Laravel, Docker, and Node work in 2026, WSL2 is the default choice. WSL1 was faster reading Windows files on /mnt/c but broke kernel-dependent tools. WSL2 gives proper ext4, inotify, ELF binaries, and near-native I/O when code lives inside the Linux filesystem.

Q: Is WSL2 free to use for development?

Yes. WSL2 ships with Windows 11 and supported Windows 10 builds at no extra cost. You pay only for your Windows licence and optional tools like Docker Desktop if you choose the GUI route over Docker Engine inside Ubuntu.

Q: How do you install WSL2 on Windows 11?

Open PowerShell as Administrator and run wsl --install. This enables WSL, Virtual Machine Platform, and installs Ubuntu by default. Reboot when prompted, create your Linux username and password, then run sudo apt update and sudo apt upgrade -y. For a specific distro, run wsl --list --online followed by wsl --install -d Ubuntu-24.04. Set WSL2 as default with wsl --set-default-version 2.

Q: Where should Laravel and Node projects be stored in WSL2 for best performance?

Clone all repositories into your Linux home directory, for example ~/projects/my-app. Files on /mnt/c/Users cross the 9P bridge on every read, making Composer and npm painfully slow on large vendor folders. Access Linux files from Windows via \\wsl$\Ubuntu\home\youruser\projects when needed. Copy shared assets into the Linux tree rather than symlinking across the boundary, because cross-boundary symlinks break inotify-dependent watchers.

Q: How do you set up PHP 8.5, Composer, and Laravel 13 on WSL2?

Add the Ondřej Surý PPA, then install php8.5 with common extensions including mysql, pgsql, redis, and bcmath. Install Composer via getcomposer.org installer. Create a Laravel 13 project with composer create-project laravel/laravel my-app, then serve with php artisan serve --host=0.0.0.0 --port=8000. Open http://localhost:8000 in your Windows browser. Laravel 13 requires PHP 8.3 or higher. Match installed extensions to your production VPS.

Q: How does Docker work with WSL2?

Docker Desktop integrates by running the engine inside your default distro or a dedicated docker-desktop distro. Enable the WSL2 backend and select Use the WSL 2 based engine in settings. Alternatively, install Docker Engine directly inside Ubuntu with docker-ce and docker-compose-plugin, then add your user to the docker group. For Laravel Sail, run sail:install and ./vendor/bin/sail up -d. WSL2 Linux containers and Windows containers are separate runtimes and should not be mixed in one compose file.

Q: Why is Composer or npm extremely slow on WSL2?

The project is almost certainly on /mnt/c instead of the Linux filesystem. Laravel vendor folders with tens of thousands of small files become painfully slow across the 9P bridge. Move the repo to ~/projects and run composer install --prefer-dist. On a mid-range laptop without .wslconfig limits, npm install can also trigger heavy memory use that slows the entire machine.

Q: How do you limit WSL2 memory and CPU usage on a laptop?

Create C:\Users\YourName\.wslconfig with a wsl2 section setting memory, processors, and swap values, for example 8GB memory, 4 processors, and 2GB swap. Enable localhostForwarding=true so Windows browsers reach services on forwarded ports. Apply changes with wsl --shutdown, then reopen your terminal. Without these caps, the WSL2 VM can grow until Windows starts swapping, which I have seen on 16 GB RAM laptops during heavy npm or PHPUnit runs.

Q: How do you fix DNS resolution failures in WSL2 behind a corporate VPN?

Create /etc/wsl.conf with generateResolvConf = false under a network section. Manually set /etc/resolv.conf to nameserver 8.8.8.8 or your office DNS. Run wsl --shutdown after changes so the config reloads. Corporate VPNs breaking WSL2 DNS is one of the most common issues across teams I work with, and fixing it inside Linux config beats abandoning WSL2 for native Windows PHP.

Q: How do you connect VS Code to your WSL2 Linux environment?

Install the WSL extension in VS Code, open a folder inside Ubuntu, and extensions run on the Linux side automatically. PHP Intelephense, Laravel Extra Intellisense, and ESLint then execute against your WSL2 PHP and Node binaries. This is the smoothest daily workflow when Windows runs browsers and design tools while Linux holds your application code and CLI tooling.

Kokil Thapa
September 11, 2026
13 min read

By Kokil Thapa | Last reviewed: September 2026

WSL2: Linux on Windows for Developers solves a problem many full-stack engineers face daily. You need real Linux tooling—bash, apt, systemd-like services, native Docker—but your laptop runs Windows for client calls, Office, or corporate policy. Dual-booting wastes time. A full VM eats RAM. Ubuntu on a dedicated Linux machine remains the production standard, yet WSL2 ships an actual Linux kernel inside Windows and gets you 90% of the way there. This guide covers install, Laravel/PHP stacks, Docker, VS Code, and the gotchas I hit on real client projects.

Quick answer: WSL2: Linux on Windows for Developers runs a lightweight Hyper-V virtual machine with a real Linux kernel. Install it via wsl --install, pick Ubuntu 24.04, put code inside the Linux filesystem, and use VS Code Remote-WSL for Laravel, Docker, and PHP 8.5 work.

What is WSL2 and how does it differ from WSL1?

Windows Subsystem for Linux (WSL) lets you run Linux userland on Windows. WSL1 translated Linux syscalls through a compatibility layer. WSL2 runs a full Linux kernel inside a lightweight utility VM backed by Hyper-V.

That architectural shift matters for developers. WSL2 gives you proper Linux behaviour: ext4 inside the distro, working inotify, native ELF binaries, and near-native I/O when files live on the Linux side. WSL1 was faster for cross-filesystem access but broke tools that depend on kernel features—Docker, certain Node watchers, and some database engines.

WSL2: Linux on Windows for Developers — Windows host, Hyper-V utility VM, real kernel, and your distro

Microsoft documents the full comparison at learn.microsoft.com/windows/wsl/compare-versions. For PHP/Laravel work in 2026, treat WSL2 as the default. Keep WSL1 only if you have a legacy edge case—and even then, migrate.

Criteria	WSL1	WSL2
Kernel	Translation layer	Real Linux kernel
Docker support	Poor / hacky	Native via Docker Desktop or engine
File I/O on `/mnt/c`	Faster cross-OS	Slower cross-OS
File I/O inside `~/`	Moderate	Near-native Linux speed
System call compatibility	Partial	Full Linux behaviour
Memory use	Lower baseline	VM overhead (~400 MB idle)
Best for	Legacy scripts on Windows files	Modern dev stacks (Laravel, Node, Docker)

On a production Linux server administration workflow, parity matters. WSL2 matches Ubuntu behaviour closely enough that most Artisan commands, Composer installs, and queue workers behave the same as on a VPS.

How do you install and configure WSL2 on Windows 11?

Installation is straightforward on Windows 11 22H2 and later. Windows 10 21H2+ also supports WSL2, but enable Virtual Machine Platform manually if the one-liner fails.

Prerequisites and one-command install

Open PowerShell as Administrator and run:

wsl --install

This enables WSL, Virtual Machine Platform, and installs Ubuntu by default. Reboot when prompted. After reboot, create your Linux username and password.

To pick a specific distro:

wsl --list --online
wsl --install -d Ubuntu-24.04

Set WSL2 as the default for new distros:

wsl --set-default-version 2

Post-install essentials

Update packages: sudo apt update && sudo apt upgrade -y
Install build tools: sudo apt install -y build-essential curl git unzip
Install Windows Terminal from the Microsoft Store for tabbed shells
Pin your distro so wsl opens the right environment
Configure Git identity inside Linux, not only on Windows

Install WSL2, configure resources via .wslconfig, then build your PHP and Node stack inside Linux

Create C:\Users\YourName\.wslconfig to cap memory and CPU so WSL2 does not consume your entire machine during npm install or PHPUnit runs:

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

Apply changes with wsl --shutdown, then reopen your terminal. I've seen laptops with 16 GB RAM struggle without these limits because the WSL2 VM grows until Windows starts swapping.

Where should you store project files for best WSL2 performance?

This is the single most important performance decision. Files on /mnt/c/Users/... cross the 9P bridge on every read. Laravel's vendor/ folder with tens of thousands of small files becomes painfully slow.

Rule: clone repositories into your Linux home directory, e.g. ~/projects/my-app. Access them from Windows via \\wsl$\Ubuntu\home\youruser\projects when needed. Do not develop directly on C:\ unless you enjoy 30-second composer install runs.

For a Laravel development environment, I use this layout:

~/projects/ — all Git repos (Laravel, WordPress themes, API services)
~/tools/ — standalone scripts and CLI utilities
~/.config/ — application config mirrored from production patterns
/mnt/c/ — read-only access to Windows downloads or client ZIP files

When you must share assets between OSes, copy files into the Linux tree rather than symlinking across the boundary. Symlinks from Linux to Windows paths break tools that expect native inotify events.

Validate JSON configs during API work with the JSON formatter tool on the web side, but keep application code inside WSL2. Mixing editors—Windows Notepad on Linux files—introduces CRLF line endings that break shell scripts and sometimes PHP autoloaders.

How do you set up PHP, Laravel, and databases on WSL2?

WSL2 is where I run PHP 8.5, Composer 2.10, Node.js 26 LTS, and MySQL 8.4 for local Laravel 13 work. The stack mirrors what I deploy on Ubuntu VPS instances for clients like Adventure Third Pole Trek and other Laravel + Livewire booking systems.

PHP and Composer

Add the Ondřej Surý PPA for current PHP builds:

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y php8.5 php8.5-cli php8.5-fpm php8.5-mysql \
  php8.5-pgsql php8.5-xml php8.5-mbstring php8.5-curl php8.5-zip \
  php8.5-bcmath php8.5-intl php8.5-redis

Install Composer:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

Create a new Laravel 13 project (requires PHP 8.3+):

composer create-project laravel/laravel my-app
cd my-app
php artisan serve --host=0.0.0.0 --port=8000

Open http://localhost:8000 in your Windows browser. WSL2 forwards localhost ports automatically when localhostForwarding=true.

MySQL and PostgreSQL

Install MySQL 8.4 (common on shared hosting) or PostgreSQL 18 for newer apps:

sudo apt install -y mysql-server
sudo mysql_secure_installation

For PostgreSQL:

sudo apt install -y postgresql postgresql-contrib
sudo -u postgres createuser --interactive

See the PostgreSQL guide for Laravel developers for schema and migration tips that apply identically on WSL2 and production.

Redis and queue workers

Redis 8.x installs cleanly:

sudo apt install -y redis-server
sudo systemctl enable redis-server

Systemd inside WSL2 is enabled by default on Ubuntu 24.04. Run queue workers with:

php artisan queue:work redis --sleep=3 --tries=3

The systemd on Linux guide explains unit files if you want queue workers to start automatically—though many developers still run them manually during local dev.

VS Code Remote-WSL edits Linux files while Windows runs browsers and design tools—standard WSL2 developer workflow

How does Docker work with WSL2 for containerised development?

Docker Desktop integrates with WSL2 by running the engine inside your default distro or a dedicated docker-desktop distro. Enable WSL2 backend in Docker Desktop settings, then check "Use the WSL 2 based engine."

Alternative: install Docker Engine directly inside Ubuntu without Docker Desktop. This suits engineers who prefer open-source tooling and do not need the Desktop GUI.

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER

Log out and back in for group membership. Test with docker run hello-world.

For Laravel Sail:

composer require laravel/sail --dev
php artisan sail:install
./vendor/bin/sail up -d

Read the companion piece on Windows containers with Docker if you also maintain .NET workloads. WSL2 Linux containers and Windows containers are separate runtimes—do not mix them in one compose file.

Official Docker WSL2 guidance lives at docs.docker.com/desktop/features/wsl. Pin image versions in compose files to match production PHP and MySQL versions.

What are common WSL2 problems and how do you fix them?

WSL2 is stable in 2026, but these issues appear repeatedly across teams I work with.

Slow Composer and npm

Cause: project on /mnt/c. Fix: move to ~/projects. Run composer install --prefer-dist to avoid cloning from source.

Port already in use

Another WSL instance or Windows service holds the port. Find it:

netstat -ano | findstr :8000

Or inside WSL:

sudo lsof -i :8000

DNS resolution failures

Corporate VPNs break WSL2 DNS. Create /etc/wsl.conf:

[network]
generateResolvConf = false

Then set /etc/resolv.conf manually to nameserver 8.8.8.8 or your office DNS. Run wsl --shutdown after changes.

High memory usage

WSL2 caches memory and releases slowly. Set memory limits in .wslconfig. Run wsl --shutdown at end of day if needed.

File permission chaos on Git

Windows tools touching Linux files can flip permissions. Configure Git inside WSL:

git config --global core.filemode false
git config --global core.autocrlf input

The Linux file permissions guide covers ACL patterns that matter when deploying from WSL2 to production servers.

Store Laravel and PHP projects in the Linux filesystem for WSL2 speed and production parity

How does WSL2 compare to a dedicated Linux machine or VPS for production work?

WSL2 excels at local development. It is not a production server. Do not expose WSL2 services directly to the internet without understanding Hyper-V networking boundaries.

For client delivery, the flow I use on web development projects remains: develop locally in WSL2, push to GitLab, deploy to Ubuntu via Deployer 7 or GitLab CI—the same pipeline described in my Linux backup automation articles for production servers.

WSL2 gaps versus a real VPS:

No public static IP or production-grade firewall without extra tunneling
Cron and mail delivery behave differently from bare metal
SSL with Let's Encrypt inside WSL2 is pointless—use staging VPS instead
Resource limits tied to your laptop, not datacenter RAM

For a legal-tech portal like Court Marriage In Nepal, I build and test forms, queues, and payment callbacks in WSL2. Staging always runs on a VPS that mirrors production PHP-FPM and MySQL configs.

VS Code Remote-WSL is the best editor integration. Install the "WSL" extension, open a folder inside Ubuntu, and extensions run on the Linux side automatically. PHP Intelephense, Laravel Extra Intellisense, and ESLint all execute against your WSL2 PHP and Node binaries.

Test regex patterns for validation rules using the regex tester in the browser while keeping application code in WSL2. Small conveniences like this add up across a work week.

If you are a full-stack developer in Nepal on a mid-range laptop, WSL2 avoids maintaining two physical machines. Power cuts make local dev critical—your stack keeps running on battery while cloud IDE sessions drop.

For enterprise apps with strict compliance, evaluate enterprise application development requirements separately. Some clients mandate macOS or native Linux hardware for audit trails. WSL2 is a productivity tool, not a compliance boundary.

Laravel official docs at laravel.com/docs/13.x/installation list prerequisites that map directly to an Ubuntu-on-WSL2 install. Match versions: PHP 8.3 minimum for Laravel 13, Node 18+ for Vite 8.x asset builds.

Run frontend builds inside WSL2 even when Node is also installed on Windows. Duplicate Node installs cause "works in one terminal, fails in another" bugs. Use nvm inside Linux:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 26
nvm use 26
node --version

Commit built assets if your production server lacks Node—as I do on several Deployer 7 pipelines—or run npm run build in CI. WSL2 is the right place to execute those builds locally before push.

Performance testing belongs on staging, but initial profiling works in WSL2. Enable OPcache in /etc/php/8.5/fpm/php.ini and mirror production settings. The testing and optimization service covers load testing that WSL2 cannot replicate at scale.

WordPress developers can run WordPress 7.1 with WooCommerce 11.1 locally using the same LAMP stack inside WSL2. Import SQL dumps via mysql < backup.sql from the Linux shell—not from PowerShell pointing at Windows paths.

When onboarding junior developers, WSL2 lowers the barrier. One wsl --install command beats partitioning disks or explaining VirtualBox networking. Document your team's .wslconfig, preferred distro, and project root path in the repo README.

Back up WSL2 distros periodically:

wsl --export Ubuntu-24.04 D:\backups\ubuntu-wsl-backup.tar

Restore with wsl --import if a distro corrupts after a bad apt experiment. This saved me twice when testing bleeding-edge PHP extensions.

Key Takeaways

Install WSL2 with wsl --install -d Ubuntu-24.04 and cap resources in .wslconfig to protect laptop RAM.
Store all code in ~/projects inside Linux—never develop Laravel or Node apps on /mnt/c.
Match production versions: PHP 8.3+ for Laravel 13, MySQL 8.4 or PostgreSQL 18, Redis 8.x, Node 26 LTS.
Use VS Code Remote-WSL and Docker Desktop's WSL2 backend for the smoothest daily workflow.
Fix DNS, port, and permission issues inside Linux config—not by moving back to native Windows PHP.
Deploy to a real Ubuntu VPS for staging and production; WSL2 is local dev only.

Ship faster with the right local stack

WSL2: Linux on Windows for Developers is the most practical way to run bash, apt, Laravel, Docker, and production-like services without leaving Windows. Install Ubuntu 24.04, keep code in ~/projects, wire up VS Code Remote-WSL, and mirror your VPS PHP and database versions. When you need staging servers, deployment pipelines, or Linux administration on real infrastructure, get in touch or browse the portfolio for Laravel systems built with this exact workflow.

Frequently Asked Questions