WSL Installation: Linux on Windows

01What Is WSL and What Is It For?

WSL (Windows Subsystem for Linux), or the Windows Linux subsystem, is a Microsoft feature that lets you run a real Linux environment inside Windows. Without setting up a virtual machine or dual booting, you open an Ubuntu terminal, install packages with apt and run bash scripts.

In web development, the vast majority of servers run Linux. Having a development environment that resembles the production server prevents file path, permission and letter-case errors that would otherwise only appear live. Node.js, Python, PHP, Ruby and most database tools install more smoothly on Linux.

WSL 1 vs. WSL 2

WSL 2 runs a real Linux kernel inside a lightweight virtual machine. This lets tools that need kernel features, like Docker, work, and operations inside the Linux file system are very fast. WSL 1 translates Linux calls to Windows; it is sometimes faster when accessing Windows files but has lower compatibility. WSL 2 is the default version on new installations and is the right choice for most users.

02Prerequisites

WSL is a Windows-only feature; macOS and Linux users don't need it because a Unix-based terminal is already built in. On the Windows side, a few requirements apply.

• Windows 11 or Windows 10 version 2004 (build 19041) or later; you can see your version with the winver command.
• Virtualization (Intel VT-x or AMD-V/SVM) must be enabled in the BIOS/UEFI settings. In Task Manager's Performance tab, check for Virtualization: Enabled under CPU.
• A user account with administrator rights.
• A few GB of free disk space for the distribution and tools.

03Installing WSL 2 with One Command

Right-click PowerShell in the Start menu and choose Run as administrator. The command below enables the WSL and Virtual Machine Platform features, downloads the Linux kernel and installs Ubuntu.

1. Restart the computer when the installation finishes.
2. On startup, the Ubuntu window appears by itself and unpacks files; this may take a few minutes.
3. Set a Linux username and password. This account is independent of your Windows account; the password is requested for sudo commands.
4. Update the package list and upgrade the system.

wsl --install

First Update and Verification

Update the packages in the Ubuntu terminal, then list the installed distributions and their versions in PowerShell. If you see 2 in the VERSION column, WSL 2 is working.

sudo apt update && sudo apt upgrade -y

wsl -l -v
wsl --status

04Choosing and Managing a Distribution

The default distribution is Ubuntu, but Debian, openSUSE and others can also be installed. Running Ubuntu on Windows is the easiest way to start because it matches most tutorials and documentation exactly.

• wsl --list --online lists the distributions you can install.
• wsl --set-version moves a distribution installed with WSL 1 to WSL 2.
• wsl --shutdown shuts down all distributions and the WSL virtual machine; it is needed after configuration changes.
• Use wsl --export to back up a distribution and wsl --import to restore it.

wsl --list --online
wsl --install -d Debian
wsl --set-default Ubuntu
wsl --set-default-version 2
wsl --set-version Ubuntu 2
wsl --update
wsl --shutdown

05Where Should Your Files Live?

Two file systems live side by side in WSL. Windows drives appear inside Linux under paths like /mnt/c, while Linux files open in Windows Explorer at \\wsl.localhost\Ubuntu. For easy access in Explorer, you can type explorer.exe . in the Ubuntu terminal.

The golden rule is this: keep your project files in the Linux file system (for example /home/kullanici/projeler). npm install, git status or build commands that run under /mnt/c slow down noticeably because of translation between the two systems, and file watching (hot reload) sometimes doesn't work at all. The speed of the development environment affects team productivity as much as production-side work like speed and performance optimization.

06Connecting VS Code, Git and Docker

What makes WSL really powerful is that it works together with tools on Windows. The code editor opens in Windows, but the commands, extensions and terminal run inside Linux.

VS Code

Install Microsoft's WSL extension in VS Code. When you go into the project folder in the Ubuntu terminal and type code . , the editor opens in WSL mode and a connection indicator appears at the bottom left.

Git

Configure Git separately inside Linux; Git settings on Windows don't carry over to WSL. For detailed settings, see our Git installation guide.

sudo apt install git -y
git config --global user.name 'Ad Soyad'
git config --global user.email ad@ornek.com
git config --global core.autocrlf input

Docker

Docker Desktop uses the WSL 2-based engine in its settings and integrates with the distributions you choose; this way you run docker commands from the Ubuntu terminal. The steps are in the Docker installation article. If you'd rather install the database directly on Ubuntu instead of in a container, the Linux steps in the PostgreSQL installation guide work in WSL exactly as written.

07A Typical Development Workflow in WSL

After setup is done, daily work settles into a routine of a few steps. You open the Ubuntu terminal, go into the project folder in your home directory and start the editor with code . . You install Node.js with nvm, Python with venv, and the database with apt or Docker; all of it runs with the same commands as the Linux environment on the live server.

This setup makes a difference especially in projects where several systems talk to each other. For example, testing integration code that communicates with a store's stock, shipping and accounting services locally on Linux reduces surprises after launch. Industry-specific software solutions such as reservation or listing management mostly run on Linux servers too, so they are developed and tried in the same environment.

When you work as a team, having everyone use the same distribution and the same tool versions prevents works on my machine problems. Writing the setup steps in a README file or a setup script lets a newcomer prepare their environment in minutes.

08Memory and Resource Settings

WSL 2 uses memory as it needs it and can slow Windows down during long sessions. To set limits, create a .wslconfig file in your Windows user folder (C:\Users\kullanici). After the change, restart WSL with wsl --shutdown.

[wsl2]
memory=4GB
processors=2

09Common Errors and Fixes

Most WSL installation errors come from virtualization being turned off or from missing Windows components. Note the error code and compare it with the table below.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart