How to Configure Windows Subsystem for Linux (WSL) on Windows Server 2025

How to Configure Windows Subsystem for Linux (WSL) on Windows Server 2025

Windows Subsystem for Linux (WSL) brings a full Linux kernel and user-space environment directly to Windows, enabling developers and administrators to run Linux tools, shell scripts, and even containerised workloads without a separate virtual machine. On Windows Server 2025, WSL is supported on the Desktop Experience installation option and requires explicit feature enablement. Once configured, WSL2 — the second-generation architecture backed by a lightweight Hyper-V VM — delivers near-native Linux performance with full system call compatibility. This tutorial covers enabling WSL, installing WSL2 with a Linux distribution, customising the environment with wsl.conf and .wslconfig, accessing Windows files from Linux, using Linux tooling on Windows Server, and running Docker within a WSL2 environment.

Prerequisites

• Windows Server 2025 with Desktop Experience installation (WSL is not supported on Server Core)
• Hyper-V feature enabled (required by WSL2 architecture)
• Virtualization enabled in BIOS/UEFI on physical hosts or nested virtualisation on VMs
• Internet connectivity for downloading Linux distribution packages
• PowerShell 5.1 or later with administrative privileges
• A user account (WSL runs per-user, not system-wide)

Step 1: Enable the WSL Windows Optional Feature

The Windows Subsystem for Linux must first be enabled as a Windows optional feature. The Virtual Machine Platform feature is also required for WSL2:

# Enable Windows Subsystem for Linux
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart

# Enable Virtual Machine Platform (required for WSL2)
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart

# Enable Hyper-V (if not already enabled — needed for WSL2 VM backend)
Install-WindowsFeature -Name Hyper-V -IncludeManagementTools -NoRestart

# Reboot to apply all changes
Restart-Computer

After the reboot, verify the features are enabled:

# Verify WSL feature is enabled
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

# Verify Virtual Machine Platform
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

Step 2: Install the WSL2 Linux Kernel and Set Default Version

On newer builds of Windows Server 2025, the wsl --install command handles everything including the kernel update. On older builds, you may need to download the WSL2 kernel package manually:

# Modern approach — install WSL with default Ubuntu distribution
wsl --install

# If the above does not work on your build, manually download and install
# the WSL2 Linux kernel update package
Invoke-WebRequest -Uri "https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi" `
    -OutFile "$env:TEMPwsl_update_x64.msi"
Start-Process msiexec.exe -ArgumentList "/i $env:TEMPwsl_update_x64.msi /quiet" -Wait

# Set WSL2 as the default version for all future distributions
wsl --set-default-version 2

# Verify current WSL version
wsl --version

Step 3: Install a Linux Distribution

Multiple Linux distributions are available through the WSL store. Install Ubuntu 24.04 LTS as it is the most commonly used and well-supported distribution:

# List all available distributions
wsl --list --online

# Install Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

# Alternatively, install other distributions
wsl --install -d Debian
wsl --install -d OracleLinux_9_1

# After installation, list installed distributions with their WSL version
wsl --list --verbose

# If an existing distribution is running WSL1, upgrade it to WSL2
wsl --set-version Ubuntu-24.04 2

The first launch of the newly installed distribution will prompt you to create a UNIX username and password. These credentials are independent of your Windows account.

Step 4: Launch and Verify the WSL Environment

Once installed, launch the distribution and perform basic verification:

# Launch the default WSL distribution
wsl

# Or launch a specific distribution
wsl -d Ubuntu-24.04

# Inside WSL — check the Linux kernel version
uname -r

# Check Linux distribution information
cat /etc/os-release

# Check available memory (reflects .wslconfig limits if set)
free -h

# Check CPU count visible inside WSL2
nproc

# Update the Ubuntu package index and upgrade packages
sudo apt update && sudo apt upgrade -y

Step 5: Customise WSL with wsl.conf and .wslconfig

Two configuration files control WSL behaviour. /etc/wsl.conf is a per-distribution configuration file located inside the Linux filesystem. .wslconfig is a global file placed in your Windows user profile that controls WSL2 VM-level settings.

Edit the per-distribution configuration inside WSL:

# Inside WSL — edit /etc/wsl.conf with your preferred editor
sudo nano /etc/wsl.conf

Example /etc/wsl.conf content:

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"
mountFsTab = true

[network]
hostname = wsl-server2025
generateHosts = true
generateResolvConf = true

[interop]
enabled = true
appendWindowsPath = true

[boot]
systemd = true

Create the global .wslconfig file in your Windows user profile directory:

# PowerShell — create .wslconfig in the user profile
$wslconfig = @"
[wsl2]
memory=4GB
processors=4
swap=2GB
swapFile=%USERPROFILE%AppDataLocalTempswap.vhdx
localhostForwarding=true
nestedVirtualization=true

[experimental]
autoMemoryReclaim=gradual
"@

$wslconfig | Set-Content -Path "$env:USERPROFILE.wslconfig" -Encoding UTF8

# Restart WSL for changes to take effect
wsl --shutdown
wsl -d Ubuntu-24.04

Step 6: Accessing Windows Files from WSL

WSL2 automatically mounts Windows drives under /mnt/. The C: drive is accessible at /mnt/c/:

# Inside WSL — navigate to the Windows C: drive
ls /mnt/c/

# Access Windows user profile from WSL
ls "/mnt/c/Users/$USER/"

# Copy a file from Windows to the WSL home directory
cp /mnt/c/Users/Administrator/Documents/script.sh ~/script.sh
chmod +x ~/script.sh

# Access WSL filesystem from Windows Explorer
# Navigate to \wsl$Ubuntu-24.04 in Explorer or File Explorer address bar

# From PowerShell, access WSL filesystem path
Get-ChildItem "\wsl$Ubuntu-24.04home"

For best I/O performance, store files you work with intensively inside the WSL filesystem (e.g., ~/projects/) rather than on the Windows drive mount, as cross-filesystem access has additional overhead.

Step 7: Using Linux Tooling on Windows Server

WSL enables Linux-native tools to be used directly from PowerShell or Command Prompt via the wsl command:

# Run a Linux command from PowerShell without entering WSL
wsl grep -r "ErrorCode" /mnt/c/Logs/

# Use Linux awk to process a Windows log file
wsl awk '{print $1, $4}' /mnt/c/inetpub/logs/LogFiles/W3SVC1/u_ex260517.log

# Use curl from WSL (often more capable than the Windows version)
wsl curl -s https://api.ipify.org

# Run a bash script from PowerShell
wsl bash /home/adminuser/maintenance.sh

# Use sed to find/replace in a file
wsl sed -i 's/old_value/new_value/g' /mnt/c/Config/app.conf

# Install and use common Linux development tools
wsl sudo apt install -y git python3-pip nodejs npm jq

Step 8: Running Docker in WSL2

Docker Desktop is not supported on Windows Server, but Docker Engine can be installed natively inside a WSL2 distribution using the standard Linux installation method:

# Inside WSL2 (Ubuntu-24.04) — install Docker Engine
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
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 chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker apt repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] 
    https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | 
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start Docker service (requires systemd=true in wsl.conf)
sudo systemctl enable --now docker

# Add your user to the docker group to avoid using sudo
sudo usermod -aG docker $USER

# Verify Docker is running
docker run --rm hello-world

Conclusion

WSL on Windows Server 2025 bridges the gap between the Windows administration environment and the Linux tooling ecosystem that many modern DevOps workflows depend on. By enabling WSL2 with its Hyper-V-backed kernel, installing a distribution such as Ubuntu 24.04, and customising performance through .wslconfig and wsl.conf, you gain a productive Linux environment directly on your Windows Server host. From running shell scripts and using Linux command-line utilities in PowerShell sessions to running a full Docker Engine inside WSL2, the integration is deep and practical. While WSL is limited to Desktop Experience installations, it provides a compelling productivity boost for mixed Windows/Linux environments, scripting-heavy administration tasks, and development workflows that require Linux-native toolchains.