How to Install WSL2 on Windows Server 2025 (Including Server Core)

On Windows Server 2025 you can install WSL2 with one command from an elevated PowerShell prompt, wsl.exe --install, plus a reboot. The same command works on Server Core, which has no Start menu and no Microsoft Store. This guide covers that install, picking a distro other than Ubuntu, NAT vs mirrored networking on a server, and moving files between Windows and Linux.

It also covers when to skip WSL2 and build a dedicated Hyper-V Linux VM instead. Short version: WSL2 is great for Linux tooling on a Windows box. A production Linux server belongs in a real VM.

What WSL2 on Windows Server 2025 Is (and Isn’t)

WSL2 runs a real Linux kernel inside a lightweight utility VM that Windows manages for you. You get a full distro userspace with apt, bash, and Linux-only CLI tools. You launch it from the same console you use for Windows admin work. There’s no separate VM to provision, patch, or back up.

The limits you’ll hit on a server:

• It isn’t a boot-time service. A registered distro doesn’t run until something launches it: an admin running wsl, or a scheduled task that calls wsl.exe. WSL can also shut an idle distro down on its own; .wslconfig exposes this as instanceIdleTimeout. Nothing runs at server boot unless you build that yourself (see “Services stop when you log off” under Tips and Troubleshooting).
• It’s per-user. Distros are registered under the Windows user who installed them. A different admin account won’t see them.
• It shares the host’s network plumbing. In the default NAT mode, the Linux instance sits behind a host-managed virtual switch. Its internal IP address changes.

Microsoft documents the architectural differences between WSL1 and WSL2 in Comparing WSL Versions (Microsoft Learn, retrieved 2026-10-05).

Prerequisites

• Windows Server 2025, either Desktop Experience or Server Core
• An account with local Administrator rights
• Hardware virtualization (Intel VT-x / AMD-V) enabled in firmware, or nested virtualization enabled if Server 2025 is itself a VM
• Internet access to download the WSL package and distro, or offline packages staged for air-gapped servers
• Enough spare RAM. By default the WSL2 VM can grow to 50% of host memory, so a 16 GB homelab mini PC loses up to 8 GB under load.

Requirement	Details
OS	Windows Server 2025, Desktop Experience or Server Core. Server 2022 also supports wsl --install, but Microsoft lists the one-command path for Server Core on 2025 only. Server 2019 (version 1709 and later) and older Server Core installs use the manual install steps.
Rights	Local Administrator, in an elevated session
Virtualization	VT-x/AMD-V on bare metal, or ExposeVirtualizationExtensions on a Hyper-V guest
Storage	A few GB per distro. Each distro lives in a VHDX, so put it on an NVMe SSD if you’ll do builds in it.

Environment note: The commands below follow Microsoft’s Install WSL on Windows Server docs (retrieved 2026-10-05). The example output shows the documented format. Your exact version strings will differ.

Step-by-Step Guide

Step 1: Confirm Virtualization Is Available

Run this in PowerShell:

systeminfo.exe

Scroll to the bottom of the output. On bare metal you’ll see a Hyper-V Requirements block where every line reads Yes. If the server already runs Hyper-V, or is a guest, you’ll see this line instead:

Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed.

That’s fine. If Server 2025 is itself a Hyper-V guest, you’ll need nested virtualization. Run this on the physical host, with the guest powered off:

# Replace SRV2025-01 with your VM's name; the VM must be stopped
Set-VMProcessor -VMName "SRV2025-01" -ExposeVirtualizationExtensions $true

Step 2: Open an Elevated PowerShell Session

How you open it depends on the install type:

• Desktop Experience: right-click Windows PowerShell and choose Run as administrator.
• Server Core: sign in as an administrator. Server 2025 opens sconfig at logon. Choose option 15 (Exit to command line (PowerShell)). That session is already elevated.

Step 3: Run the One-Command Install

wsl.exe --install

This command does four things:

• Enables the Windows Subsystem for Linux and Virtual Machine Platform optional components.
• Downloads the current WSL package and Linux kernel from Microsoft (on networks that block the Microsoft Store, see the --web-download fallback in Troubleshooting).
• Sets WSL2 as the default version.
• Queues Ubuntu as the default distro.

It needs no Store and no GUI. That’s why it works on Server Core.

Expected output (wording varies by WSL release):

Installing: Virtual Machine Platform
Virtual Machine Platform has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Installing: Ubuntu
Ubuntu has been installed.
The requested operation is successful. Changes will not be effective until the system is rebooted.

Tip: If you plan to standardize on Debian or another distro, skip Ubuntu entirely. Run wsl.exe --install --no-distribution here, then pick your distro in Step 7.

Step 4: Reboot the Server

Warning: This reboot is required. The optional components don’t take effect until the server restarts. Schedule it in a maintenance window on anything that serves users.

Restart-Computer

On Desktop Experience, you can confirm the components after the reboot. Open Server Manager > Manage > Add Roles and Features > Features. (On Server, Turn Windows features on or off in Control Panel opens this same wizard.)

On either install type, PowerShell gives you the same answer faster:

Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux, VirtualMachinePlatform |
  Select-Object FeatureName, State

FeatureName State
———– —–
Microsoft-Windows-Subsystem-Linux Enabled
VirtualMachinePlatform Enabled

Step 5: Launch the Distro and Verify WSL2

wsl

On first launch, Ubuntu finishes unpacking. Then it asks you to create a Linux username and password. You do this once per distro, and the account is separate from your Windows account. Type exit to return to PowerShell, then check the version:

wsl --list --verbose

NAME STATE VERSION
* Ubuntu Stopped 2

The VERSION column must read 2. The asterisk marks the default distro.

Step 6: Update WSL and Check Versions

wsl --update   # latest WSL package; add --web-download to pull it from GitHub instead of the Store
wsl --version

WSL version: x.x.x.x
Kernel version: 6.x.x.x-1
WSLg version: 1.x.x
MSRDC version: 1.x.x
Direct3D version: 1.x.x
DXCore version: 10.0.x
Windows version: 10.0.26100.x

Release notes for each version are on GitHub. Per those notes (retrieved 2026-10-06), WSL 3.0.1, released September 29, 2026, is the stable release in which Microsoft made the WSL containers feature generally available. That’s a separate container feature, not something this guide’s distro setup depends on, so check the release notes for your installed version before you rely on it.

Step 7: Install and Switch Between Distros

You aren’t stuck with Ubuntu. Pick the distro that matches your production Linux servers, so your scripts behave the same in both places. First, list what’s available:

wsl --list --online

NAME FRIENDLY NAME
Ubuntu Ubuntu
Ubuntu-24.04 Ubuntu 24.04 LTS
Debian Debian GNU/Linux
OracleLinux_9_5 Oracle Linux 9.5
openSUSE-Tumbleweed openSUSE Tumbleweed
…

Install a distro using the exact value from the NAME column:

wsl --install -d Debian

Day-to-day commands for working with several distros:

wsl -d Debian                  # open a shell in a specific distro
wsl --set-default Debian       # make Debian what plain `wsl` launches
wsl -d Debian -- uname -r      # run one command without an interactive shell
wsl --terminate Debian         # stop one distro
wsl --shutdown                 # stop all distros and the WSL2 VM

To back up a distro before you change it, export it to a tarball:

wsl --export Debian D:\Backups\debian-2026-10-05.tar

Warning: wsl --unregister <DistroName> permanently deletes that distro’s VHDX and every file inside it. There’s no undo. Export first if you need anything in it.

Step 8: Access Files Across Windows and Linux

From Windows to Linux: each distro shows up as a network path at \\wsl.localhost\<DistroName>\. The shorter \\wsl$\<DistroName>\ path also works. On Desktop Experience, paste the path into the File Explorer address bar:

\\wsl$\Ubuntu\home

Server Core has no File Explorer, so use PowerShell with the same path:

Get-ChildItem \\wsl.localhost\Ubuntu\home
Copy-Item C:\Scripts\deploy.sh \\wsl.localhost\Ubuntu\tmp\

From Linux to Windows: Windows drives are mounted under /mnt/:

ls /mnt/c/Users/Administrator
cp /mnt/d/exports/report.csv ~/

Cross-OS file access goes through a translation layer. It’s noticeably slower than native access. Keep files on the side that does the work, so put Linux builds in ~/ inside the distro, not in /mnt/c/.

Configuration

WSL2 VM settings live in %UserProfile%\.wslconfig on the Windows side. They apply to all of that user’s WSL2 distros, but the file is per Windows user: another admin account, or a scheduled task running as a service account, reads its own profile’s .wslconfig, not yours. Per-distro settings, such as systemd and automount, live in /etc/wsl.conf inside each distro. Networking mode is a VM setting, so it goes in .wslconfig.

NAT vs Mirrored Networking

Mode	How it behaves	Good for	Server pain points
nat (default)	Linux gets a private IP behind a host virtual switch. localhost forwarding works from the host itself.	Outbound tools, local dev	The internal IP changes on restart. Inbound traffic from other machines needs netsh port proxies.
mirrored	Linux shares the host’s network interfaces and IP addresses	Services that other machines must reach	Microsoft documents it for Windows 11 22H2 and later only, not Windows Server. Inbound traffic is governed by the Hyper-V firewall. Port conflicts with Windows services are possible.

On a desktop, NAT rarely gets in the way. On a server, other machines usually need to reach whatever you run. NAT is the documented, supported path, and that means a port proxy that you must refresh every time the WSL IP changes. Run this from an elevated PowerShell session:

# NAT mode only: forward host port 8080 to the current WSL IP
$wslIp = (wsl hostname -I).Trim().Split(" ")[0]
# Remove any stale rule for this port first, then add the current one
netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=$wslIp
netsh interface portproxy show all
# Allow the listening port through Windows Firewall on the host
if (-not (Get-NetFirewallRule -DisplayName "WSL portproxy 8080" -ErrorAction SilentlyContinue)) {
  New-NetFirewallRule -DisplayName "WSL portproxy 8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow
}

The delete line returns an error the first time, when no rule exists yet. That’s harmless.

Mirrored mode would remove that chore, but treat it as an experiment on Server 2025. Microsoft’s WSL networking and WSL configuration docs list networkingMode as requiring Windows 11 22H2 or later and don’t mention Windows Server. If you want to test it, create or edit the .wslconfig in the profile of the account that runs WSL (here, C:\Users\Administrator\.wslconfig):

# C:\Users\Administrator\.wslconfig
[wsl2]
networkingMode=mirrored
memory=8GB        # cap the WSL2 VM; default is 50% of host RAM
processors=4      # cap vCPUs; default is all logical processors

Next, allow inbound traffic through the Hyper-V firewall. The VMCreatorId value below is the fixed ID Microsoft documents for WSL:

New-NetFirewallHyperVRule -Name "WSL-HTTP-8080" -DisplayName "WSL inbound 8080" `
  -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' `
  -Protocol TCP -LocalPorts 8080

Apply the change by shutting down the WSL2 VM:

wsl --shutdown

Then run wsl hostname -I and check that it returns the host’s LAN address. If it doesn’t, mirrored mode isn’t working on your build: remove the networkingMode line, run wsl --shutdown again, and use the NAT port proxy above. Don’t build anything that other machines depend on around an unsupported mode.

Tips and Troubleshooting

wsl --install only prints help text

Why it happens: The WSL component is partly present, or the build handles the simple install path differently.

Fix: Install a distro by name. Run wsl --list --online, then wsl --install -d Ubuntu-24.04.

Install progress stalls at 0.0%

Why it happens: A proxy or firewall blocks the default download method. That’s common on locked-down server networks.

Fix: Use the web-download fallback:

wsl --install --web-download -d Ubuntu-24.04

Error 0x80370102 or “Virtual Machine Platform” error on launch

Why it happens: Either the VirtualMachinePlatform component is off, or virtualization is hidden from the server. Nested Hyper-V guests usually hit the second case.

Fix: Enable the component, reboot, then recheck Step 1:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart-Computer

Distro shows VERSION 1

Why it happens: An older install or an imported distro defaulted to WSL1.

Fix:

wsl --set-default-version 2
wsl --set-version Ubuntu 2

Offline or air-gapped servers

Why it happens: wsl --install needs internet access.

Fix: Follow the manual install path:

• Enable both components with dism.exe. Use the command above, plus /featurename:Microsoft-Windows-Subsystem-Linux.
• Reboot.
• Copy the WSL .msi from the GitHub releases page and install it with msiexec /i.
• Import a staged distro image:

wsl --import Debian D:\WSL\Debian D:\Staging\debian-rootfs.tar

Services stop when you log off

Why it happens: WSL is built around interactive user sessions, not boot-time services. Distros belong to the Windows user who registered them, and WSL can shut a distro down once it’s idle. Microsoft’s WSL configuration docs list this as instanceIdleTimeout under [general] in .wslconfig, with -1 disabling auto shutdown. Exactly when your services stop depends on your WSL release and what’s still running, so test it on your own server before you rely on it.

Fix: You can keep a distro alive with that setting or start it with a scheduled task. If you’re reaching for those workarounds, read the next section first.

WSL2 vs a Full Hyper-V Linux VM

Use this as the line:

Choose WSL2 when…	Choose a Hyper-V Linux VM when…
You need Linux CLI tools alongside Windows admin work	The workload must survive reboots and run with no user logged in
Workloads are short-lived: scripts, builds, testing	Other machines depend on it, with uptime expectations
One admin uses it interactively	Several admins or service accounts need the same instance
You accept a host-managed kernel and network	You need specific kernel modules, a static IP, VLAN tagging, or strict network segmentation
Shared resources are fine	You need guaranteed CPU/RAM reservations and VM-level backup or replication

Systemd works in WSL2. Set systemd=true under [boot] in /etc/wsl.conf, and current Ubuntu images turn it on by default. So the real deciding factor is lifecycle. A Hyper-V guest starts at boot, has its own identity on the network, and fits your existing backup tools. If someone will page you when the service is down, put it in a VM on a server with a proper UPS behind it.

Wrapping Up

You now have WSL2 running on Windows Server 2025, on Desktop Experience or headless Server Core. You can install the distro your team uses, expose a Linux service to the network with a NAT port proxy (or test mirrored mode), and move files both ways.

My take: WSL2 is excellent at removing the “spin up a VM just to run rsync and jq” chore. It gets risky when it quietly turns into production infrastructure. Treat it as a toolbox, and send anything that has to stay up to Hyper-V.

Step	Action	Applies To
1–2	Check virtualization, open an elevated shell	Desktop Experience and Core
3–4	wsl.exe --install, reboot	Server 2025 (including Core) and Server 2022
5–7	Verify VERSION 2, update, add distros	All
8	\\wsl.localhost\ and /mnt/c/	All (File Explorer on Desktop Experience only)
Config	.wslconfig networking and resource caps	All

Resources

• Install WSL on Windows Server
• Install WSL (command reference)
• Manually install older versions of WSL
• Comparing WSL Versions
• WSL GitHub Releases