LinuxTechnology

How to Install WSL on Windows: Setup, Architecture, and Troubleshooting

Updated on
10 min read

Windows Subsystem for Linux (WSL) gives Windows users a Linux environment without a traditional dual-boot setup. This guide explains how to install WSL, what happens under the hood, and how to configure it for development, automation, containers, and everyday command-line work.

What Is WSL?

WSL is a Windows feature that runs Linux distributions alongside Windows applications. A distribution supplies the Linux user space: the shell, package manager, libraries, and tools you install. WSL provides the integration layer that connects that user space to Windows.

WSL 2 is the default choice for most new installations. It runs a real Linux kernel inside a lightweight managed virtual machine, which provides broad Linux system-call compatibility. WSL 1 uses a translation layer instead of a Linux kernel and can still be useful for narrow workloads that frequently access files on the Windows filesystem.

WSL is not the same as a full desktop virtual machine. You can launch Linux commands from Windows, run Windows executables from Linux, and access both operating systems’ filesystems. Optional graphical application support is provided by WSLg on supported Windows configurations; a graphical desktop is not required for normal WSL use.

Why Use WSL Instead of Dual Booting or a Traditional VM?

Developers often need Linux-native tools while keeping Windows applications, device support, and enterprise management. Dual booting separates the environments and requires a restart. A conventional VM provides a complete guest operating system but generally needs more explicit CPU, memory, storage, and networking configuration.

WSL reduces that friction:

  • Linux tooling on demand: Use Bash, apt, SSH, Git, compilers, and scripting tools from Windows Terminal.
  • Shared workflow: Open Windows projects from Linux, launch Windows editors from a Linux shell, or use an editor’s remote WSL integration.
  • Lower operational overhead: WSL 2 manages the utility VM and its Linux kernel instead of making you maintain a complete VM installation.
  • Container compatibility: Docker Desktop and other container workflows can integrate with WSL 2.

The trade-off is that WSL is a local development and administration environment, not a replacement for every server or desktop Linux deployment. Kernel modules, device access, long-running services, and production networking can behave differently from a physical Linux host.

How WSL Works: Architecture and Data Flow

The main WSL 2 path looks like this:

Windows host → WSL service → managed utility VM → Microsoft-provided Linux kernel → distribution instance → Linux processes

Each installed distribution has its own root filesystem, users, packages, and configuration. WSL 2 stores that filesystem in a virtual disk managed by Windows. The distributions share the WSL 2 kernel and VM boundary, while remaining separate environments from a user and filesystem perspective.

WSL 1 and WSL 2 Compared

Area WSL 1 WSL 2
Linux system calls Translated by the compatibility layer Handled by a real Linux kernel
Virtualization Does not use the WSL 2 utility VM Uses a lightweight managed VM
Linux filesystem workload Can be efficient for some Windows-mounted paths Usually the better choice for Linux-native tools and containers
Accessing files under /mnt/c Often faster for metadata-heavy Windows paths Cross-filesystem access can be slower than working in the Linux filesystem
Kernel-dependent tools Limited by the translation layer Broad compatibility, subject to WSL’s managed-kernel model
Best fit Specialized legacy or Windows-filesystem-heavy workflows General development, containers, services, and Linux tooling

The choice is per distribution. Check the current mode with wsl --list --verbose, and convert an installed distribution with wsl --set-version <DistroName> 2. Conversion can take time and temporarily use additional disk space.

WSL Components and Configuration Boundaries

It is easier to troubleshoot WSL when each responsibility has a clear boundary:

  • Windows-side WSL command: wsl.exe manages distributions, versions, updates, shutdown, imports, and launches.
  • Distribution: Ubuntu, Debian, Fedora, and other distributions are separate user spaces. Installing one does not install packages into another.
  • Linux user configuration: /etc/wsl.conf controls settings for one distribution, such as automount behavior, hostname, default user, and systemd support where available.
  • Global VM configuration: %USERPROFILE%\.wslconfig controls WSL 2 VM-wide resources and networking. It does not control WSL 1.
  • Windows integration: Windows drives are commonly mounted at /mnt/<drive>, while Windows can browse a distribution through \\wsl$\DistroName.
  • Networking: WSL 2 services can normally be reached from Windows through localhost. Access from other machines requires deliberate bind-address and Windows Firewall decisions.

For the supported settings and exact syntax, use Microsoft’s WSL configuration reference. Avoid copying settings between .wslconfig and wsl.conf; they apply at different scopes.

Installing WSL and a Linux Distribution

Before You Begin

Use a supported Windows release and an account that can approve administrator changes. WSL 2 also requires hardware virtualization to be enabled in firmware and available to Windows. If the computer is itself a virtual machine, nested virtualization may need to be enabled by the host.

Back up important files before importing or moving distributions. WSL distributions are not a substitute for a backup strategy, and a command such as wsl --unregister permanently removes the selected distribution and its data.

Open PowerShell as Administrator and run:

wsl --install

This enables the required Windows components, installs the WSL package and a default distribution when available, and may request a restart. The exact distribution and restart behavior can vary with the Windows build and existing WSL state. Microsoft’s WSL installation guide documents the supported paths.

To install WSL without selecting a default distribution, use:

wsl --install --no-distribution

List distributions that can be installed, then choose one explicitly:

wsl --list --online
wsl --install --distribution Ubuntu

After the restart, launch the distribution from the Start menu or run wsl. The first launch expands the distribution, asks for a Linux username and password, and creates the initial user. The Linux password is separate from the Windows password and is required for sudo.

Verify the Installation

Run these commands from PowerShell:

wsl --status
wsl --list --verbose
wsl --version

wsl --list --verbose shows each distribution and whether it uses WSL 1 or WSL 2. wsl --status reports the default distribution and kernel information. wsl --version is available with the modern WSL package; if the command is unavailable, update WSL or consult the installed Windows feature’s documentation.

Inside the distribution, update packages and install a small baseline toolset:

sudo apt update
sudo apt upgrade
sudo apt install git curl build-essential

The package manager and package names depend on the distribution. Do not run Linux package commands in PowerShell, and do not assume that installing a package in one distribution installs it in another.

Manual or Recovery Installation

If wsl --install is unavailable or a managed machine blocks the one-command setup, enable the Windows features from an elevated PowerShell session:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
Restart-Computer

After restarting, update WSL and choose the default version:

wsl --update
wsl --set-default-version 2

Install a distribution through the Microsoft Store, the command line, or an imported tar file. Follow the distribution’s instructions for its initial user and package setup.

Practical Configuration for Development

Keep Linux Projects in the Linux Filesystem

Store active Linux builds and source trees under /home/<user>/projects when Linux tools perform frequent metadata operations. Accessing a project under /mnt/c is convenient, but cross-filesystem translation can make package installation, dependency resolution, and source-control operations noticeably slower.

Windows applications can open Linux-side files through a path such as \\wsl$\Ubuntu\home\<user>\projects. The Microsoft WSL filesystem guidance explains the boundary and the safety considerations. Avoid editing the same files concurrently with tools that disagree about permissions, line endings, or file watching.

Set Resource Limits

WSL 2 can consume memory and processor time dynamically. If it competes with Windows applications, create %USERPROFILE%\.wslconfig with only the limits you need:

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

Apply changes by stopping the WSL 2 VM:

wsl --shutdown

These limits apply to the WSL 2 VM, not to a single distribution. Start with conservative values and monitor whether builds, language servers, and containers still have enough capacity.

Configure the Distribution

Distribution-specific settings belong in /etc/wsl.conf. For example, a distribution can use systemd when the installed WSL and distribution versions support it:

[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

Restart the distribution or run wsl --shutdown after changing the file. Enable only the integration you need; allowing Windows executables and Windows paths inside Linux can be convenient but also expands the commands and files available across the trust boundary.

Networking and Containers

Run a development service inside WSL and test it from Windows:

python3 -m http.server 8000 --bind 127.0.0.1

Then open the local development URL in a Windows browser. For access from another device, binding to 0.0.0.0 is only one part of the solution: configure the Windows Firewall and understand whether the current WSL networking mode forwards that port. Microsoft’s WSL networking documentation covers localhost forwarding, mirrored networking, DNS, and network access details.

For a multi-service local stack, Docker Desktop can integrate with selected WSL distributions. The related guide to Docker Compose for local development shows how to define services, networks, and volumes.

Real-World WSL Use Cases

  • Web and application development: Run Linux-native language runtimes, package managers, build tools, and test suites while using Windows editors and browsers.
  • Infrastructure work: Use SSH, cloud CLIs, Git hooks, and shell automation without maintaining a separate Linux workstation.
  • Container development: Pair WSL 2 with Docker Desktop or another supported runtime for a Linux-oriented container workflow.
  • Education and experimentation: Try distributions, networking commands, and Linux administration safely without repartitioning the boot drive.
  • Windows automation: Combine wsl.exe with PowerShell to run Linux scripts from scheduled or repeatable Windows workflows. Keep credentials and file permissions explicit when crossing the boundary.

Common WSL Misconceptions and Troubleshooting

“WSL Is a Full Virtual Machine”

WSL 2 uses a managed utility VM, but it does not expose the same lifecycle, virtual hardware model, or administration surface as a conventional VM. It is optimized for Windows integration and local workloads.

“Every Linux Program Works Unchanged”

Most command-line and user-space tools work well, but kernel modules, low-level device access, init assumptions, filesystem semantics, and production service behavior can differ. Test software that depends on a specific kernel or device before standardizing on WSL.

“The Windows Filesystem and Linux Filesystem Are Interchangeable”

They are accessible from both sides, but they do not have identical performance and permission semantics. Keep Linux-heavy projects in the distribution filesystem and use /mnt/c when Windows-side access is the priority.

“A Distribution Reset Is Harmless”

wsl --unregister <DistroName> deletes the distribution’s virtual disk. Export before destructive maintenance:

wsl --export Ubuntu "$env:USERPROFILE\Backups\ubuntu.tar"
wsl --unregister Ubuntu

Diagnostic Checklist

  1. Run wsl --status and wsl --list --verbose to identify the installed WSL package, default distribution, and WSL version.
  2. Run wsl --update and restart Windows if the kernel or package is stale.
  3. Use wsl --shutdown after changing .wslconfig, networking settings, or a distribution’s wsl.conf.
  4. Check that BIOS/UEFI virtualization and any hypervisor policy permit WSL 2.
  5. Test filesystem location, port binding, and Windows Firewall rules separately rather than treating every failure as a Linux package problem.
TBO Editorial

About the Author

TBO Editorial writes about the latest updates about products and services related to Technology, Business, Finance & Lifestyle. Do get in touch if you want to share any useful article with our community.