WSL2 on kenji.blog

Hyper-V vs WSL2: Comparing Virtualization Technologies on Windows

Sun, 13 Sep 2026 07:00:00 +0900

1. Introduction: The Evolution of Virtualization on Windows

Virtualization technology on the Windows platform has evolved dramatically over the past few decades. In the past, third-party Type 2 hypervisors (such as VMware Workstation and VirtualBox) were the mainstream. However, since Microsoft introduced “Hyper-V” in Windows Server 2008, Type 1 hypervisors have also been integrated into desktop OSs like Windows 10/11.

In recent years, the technology that has garnered the most attention among developers is “WSL2 (Windows Subsystem for Linux 2)”. While WSL1 relied on system call translation, WSL2 employs a “Lightweight Utility VM” based on Hyper-V technology, achieving full Linux compatibility and a dramatic leap in performance.

In this article, we will thoroughly compare and explain the architecture, performance (CPU, memory, disk I/O), network configuration, and optimal use cases of these two powerful virtualization technologies—the full-featured “Hyper-V” and the developer-experience-focused “WSL2”—along with deep technical details.

2. Basic Theory of Hypervisors and Architecture Comparison

To understand virtualization technologies, classifying hypervisor (Virtual Machine Monitor: VMM) types is essential.

2.1. Differences between Type 1 and Type 2 Hypervisors

A hypervisor is a software layer that abstracts hardware access, allowing multiple OSs (guest OSs) to run simultaneously on a single physical machine.

Type 1 (Bare-metal): Runs directly on the hardware. There is no concept of a host OS (strictly speaking, a privileged management OS may exist), offering extremely low overhead, high performance, and high security. Examples: Hyper-V, VMware ESXi, Xen.
Type 2 (Hosted): Runs as an application on a host OS (such as Windows or macOS). Since all hardware access goes through the host OS, the overhead is larger. Examples: VMware Workstation, Oracle VirtualBox.

Windows Hyper-V is a pure Type 1 hypervisor. When Hyper-V is enabled, the Windows OS that the user normally operates actually starts running inside a special virtual machine called the “Root Partition”.

2.2. Hyper-V Architecture Details

The Hyper-V architecture adopts a microkernel design and is based on logical isolation units called Partitions.

graph TD
A["Hardware (CPU, RAM, Disk, NIC)"] --> B["Windows Hypervisor (Ring -1)"]
B --> C["Root Partition (Windows OS)"]
B --> D["Child Partition 1 (Windows VM)"]
B --> E["Child Partition 2 (Linux VM)"]
C --> F["VMBus (Virtual Machine Bus)"]
D --> F
E --> F
C --> G["VID (Virtualization Infrastructure Driver)"]
C --> H["VMWP.exe (Worker Process)"]

Windows Hypervisor: Runs at the most privileged level of the CPU (Ring -1 or VMX Root Mode) and is responsible only for memory allocation and CPU scheduling. It does not contain device drivers.
Root Partition: The partition where the host Windows OS runs. It possesses all device drivers and controls the hardware directly. It also provides management functions for child partitions (such as WMI providers and VMWP.exe).
Child Partition: The partition where a guest OS runs. Direct access to hardware is not permitted, and it sends I/O requests (Synthetic I/O) to the root partition via a logical memory sharing bus called “VMBus”.

2.3. Mechanism of WSL2 and Lightweight Utility VM

Although WSL2 utilizes the same underlying Type 1 hypervisor technology as Hyper-V, it uses a subset of features called the “Virtual Machine Platform (VMP)” which differs from full-featured Hyper-V virtual machines.

The “Lightweight Utility VM” adopted in WSL2 completely eliminates the emulation of legacy hardware (such as virtual BIOS or virtual motherboards) present in traditional VMs.

graph TD
A["Windows Host OS (User Space)"]
B["NTFS File System"]
C["9P Protocol Server (Plan 9)"]
D["Lightweight Utility VM (Linux Kernel)"]
E["ext4.vhdx (Virtual Disk)"]
F["Linux User Space (WSL2 Distributions)"]
A --> C
C -->| Cross-OS File Sharing | D
D --> E
D --> F

The greatest features of WSL2 are its fast startup and seamless integration with the host OS. The Linux kernel boots in less than a second, and it accesses the Windows file system (NTFS) via Plan 9’s 9P network file system protocol.

3. Thorough Performance Analysis: Computational Resources and I/O

Virtual machine performance is expressed as the sum of overheads across CPU, memory, and disk I/O components.

3.1. CPU and Context Switch Overhead

Both Hyper-V and WSL2 use hardware-assisted virtualization (Intel VT-x / AMD-V). CPU instructions are basically executed at native speed, but when privileged instructions are executed or I/O operations occur, an interrupt called “VM Exit” is triggered, resulting in a context switch to the hypervisor.

The CPU overhead $T_{overhead}$ at this time can be expressed by the following mathematical model:

$$ T_{overhead} = \sum_{i=1}^{N} (t_{vm\_exit} + t_{hypercall\_process} + t_{vm\_entry}) $$

Where:

$N$: Number of VM Exits occurring per unit time
$t_{vm\_exit}$: Transition time from the guest to the hypervisor
$t_{hypercall\_process}$: Processing time for I/O operations or interrupts via VMBus
$t_{vm\_entry}$: Return time from the hypervisor to the guest

Because WSL2 lacks legacy emulation, $t_{hypercall\_process}$ is heavily optimized and extremely small. Therefore, for pure CPU operations (such as kernel compilation or machine learning model inference), the performance degradation remains within a few percent compared to a bare-metal environment.

3.2. Memory Allocation Mechanisms

There are distinct differences in design philosophy between the two regarding memory management approaches.

Hyper-V (Dynamic Memory): The root partition dynamically allocates and reclaims memory according to the memory demands of the guest VM. However, memory secured as page cache within the guest OS tends not to be released unless the system is under pressure.
WSL2 (Dynamic Memory Reclaim): WSL2 has its own mechanism to periodically return (reclaim) memory—including caches—that is no longer needed inside the Linux VM back to the Windows host. While early WSL2 versions had an issue where Linux page caches exhausted Windows memory (bloat of the Vmmem process), this has now been improved by kernel patches.

3.3. Disk I/O Characteristics (VHDX vs ext4.vhdx)

Disk I/O is the component most likely to become a bottleneck in virtual machine performance.

The I/O latency $L_{total}$ is calculated as follows:

$$ L_{total} = L_{guest\_fs} + L_{vmbus} + L_{host\_fs} + L_{physical\_disk} $$

In the case of Hyper-V: A typical Hyper-V guest uses a virtual disk in the VHDX format. I/O requests issued from the file system (ext4 or NTFS) within the guest OS pass through the VMBus block device storage driver (storvsc) and are processed as accesses to the VHDX file on NTFS on the Windows side.

In the case of WSL2: WSL2’s Linux distributions run on a native ext4 file system built within a dedicated ext4.vhdx file. File operations inside Linux (e.g., within the ~ directory) demonstrate native performance equivalent to the aforementioned Hyper-V. However, when accessing files on the Windows side (such as /mnt/c/) from WSL2’s Linux, or vice versa, the processing differs significantly. The 9P (Plan 9 File System Protocol) is used for this cross-OS access.

$$ L_{cross\_os} = L_{9p\_client} + L_{socket\_transfer} + L_{9p\_server} + L_{ntfs} $$

Access via this 9P protocol involves significant serialization processing overhead. In scenarios involving massive read/write operations of small files (e.g., npm install or Git operations in a Node.js project located in a Windows directory), performance drops significantly (sometimes with more than 10 times the delay). Therefore, when using WSL2, the golden rule is to always place project files on the Linux native file system (under ~/).

4. Network Structure: NAT, Default Switch, Bridged

Network flexibility is one of the major differences between Hyper-V and WSL2.

4.1. WSL2 Network (NAT-based)

By default, the WSL2 network is configured with “NAT (Network Address Translation)” using Hyper-V’s virtual switch technology. The Linux VM is automatically assigned a private IP address (e.g., 172.20.x.x) different from the Windows host. A mechanism is built-in where access to localhost from the Windows host is forwarded to services (ports) running inside WSL2, allowing developers to test web servers without having to be mindful of the network.

Recently, a new network mode called “Mirrored mode” was introduced in preview versions of WSL2. This aims to improve IPv6 support and VPN connection compatibility (configurable via .wslconfig).

4.2. Hyper-V Virtual Switch

Hyper-V enables advanced, enterprise-level network construction. Through the “Virtual Switch Manager”, it mainly provides three modes:

External: Binds the host machine’s physical NIC to the virtual switch, allowing the guest VM to directly join the physical network (bridge connection). The VM obtains an IP from the same subnet as the physical network via a DHCP server.
Internal: Only allows communication between the host OS and VMs, as well as between VMs. Direct access to external networks is not possible.
Private: Only allows communication between VMs, cutting off communication with the host OS. Used for building isolated testing environments.

4.3. Advanced Hyper-V Network Construction using PowerShell

In development or testing environments, when you want to build a customized NAT network for VMs, PowerShell allows for detailed control. Below is an example script to create an internal virtual switch, configure NAT on it, and provide internet access to a VM.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 1. Create Internal Virtual Switch
$SwitchName = "HyperV-NatSwitch"
New-VMSwitch -SwitchName $SwitchName -SwitchType Internal

# 2. Set IP address to the virtual NIC on the host side (IP that acts as a gateway)
$GatewayIP = "192.168.100.1"
$NetPrefix = 24
$InterfaceAlias = "vEthernet ($SwitchName)"
New-NetIPAddress -IPAddress $GatewayIP -PrefixLength $NetPrefix -InterfaceAlias $InterfaceAlias

# 3. Configure NAT Network
$NatName = "HyperV-NatNetwork"
$NatSubnet = "192.168.100.0/24"
New-NetNat -Name $NatName -InternalIPInterfaceAddressPrefix $NatSubnet

# Verification command
Get-NetNat

With this configuration, by manually setting an IP of 192.168.100.x and a gateway of 192.168.100.1 on a designated Hyper-V guest, you can build a custom NAT segment that can communicate externally via the host.

5. Use Cases and Practical Selection Guide

Based on the differences in architecture and performance discussed so far, we define under what circumstances which technology should be adopted.

5.1. Scenarios for Choosing WSL2

WSL2 is specifically designed to “improve developer productivity.” It is optimal for the following uses:

Web Development and Cloud-Native Development: Container development using Docker Desktop (WSL2 backend) or Podman.
Using Linux-specific Tools: When routinely using bash, grep, awk, sed, or GCC/Clang compilers meant for Linux.
GUI Applications (WSLg): When you want to run Linux X11/Wayland applications seamlessly on the Windows desktop.
Machine Learning and AI Development: High-speed training with TensorFlow or PyTorch using GPU passthrough capabilities (NVIDIA CUDA on WSL).

Note: You may face restrictions if you wish to deeply customize the kernel, or build complex services heavily dependent on systemd (systemd is currently supported, but is disabled or restricted by default).

5.2. Scenarios for Choosing Hyper-V

Hyper-V is intended for “infrastructure virtualization and complete isolation.” It is essential for the following uses:

Running Windows VMs: When running different versions of Windows (such as Windows Server or older Windows 10) as test environments.
Nested Virtualization: When you want to run a virtual machine (Hyper-V or KVM) inside another virtual machine. Indispensable for infrastructure engineers’ validation environments.
Advanced Network Requirements: When network configurations must be strictly controlled, such as external bridge connections (joining the same LAN), VLAN tagging, or allocating multiple NICs.
Snapshots (Checkpoints): The ability to save a VM’s state at a specific point in time and instantly roll back to it whenever needed. Extremely useful for destructive software testing or malware analysis.
Fixed Resource Allocation: When you want to strictly fix the number of CPU cores and memory amount to minimize the impact on the host OS.

6. Consideration of I/O Throughput through Mathematical Models (Appendix)

As a system engineer, when determining the I/O performance limits of both, it is crucial to theoretically understand the relationship between throughput $S$ and block size $B$.

Data transfer throughput $S$ is the amount of data transferred per unit time, and is modeled as follows:

$$ S(B) = \frac{B}{L_{setup} + \frac{B}{R_{max}}} $$

$B$: Block size (Bytes)
$L_{setup}$: Fixed latency associated with I/O request setup and context switching
$R_{max}$: Hardware’s maximum bandwidth for copying and device transfers

In file accesses via WSL2’s 9P protocol, this $L_{setup}$ becomes extremely large (due to socket communication and protocol serialization/deserialization). Therefore, when the block size $B$ is small (massive read/write of fine files around a few KBs), the effect of $L_{setup}$ in the denominator becomes dominant, and the throughput $S$ degrades dramatically. Conversely, in VHDX access via Hyper-V’s VMBus, $L_{setup}$ is optimized to a level close to hardware interrupts, allowing it to maintain high IOPS even with small blocks.

This mathematical reality serves as the logical foundation for the best practice that “you must not place project files on the Windows side in WSL2”.

7. Conclusion: Two Coexisting Virtualization Technologies

Hyper-V and WSL2 are not a matter of one being superior to the other; they are “two solutions with different purposes”.

WSL2 is the “best integration tool” that breaks the shell of the Windows OS to seamlessly and swiftly deliver the Linux ecosystem to Windows users. It is no exaggeration to call it the ultimate CLI environment for developers.
Hyper-V is a “full-fledged hypervisor” that brings the robust isolation and management capabilities cultivated in enterprise data centers to the desktop. It is second to none in network construction, Windows OS testing, and infrastructure environment simulation.

In modern Windows environments, these two technologies do not compete on equal terms; they beautifully coexist on the same VM platform. By using the right tool for the right job depending on the purpose, Windows can truly become the most powerful and flexible engineering workstation in the world.

The Ultimate Development Environment Setup Guide for WSL2 (Windows Subsystem for Linux)

Sat, 12 Sep 2026 23:00:00 +0900

WSL2 (Windows Subsystem for Linux 2), which provides a Linux-native development environment on Windows, has become an indispensable tool in modern software development. However, there is a world of difference in performance and development experience between continuing to use it in its default state and understanding the architecture to apply appropriate tuning.

In this article, starting with an explanation of the architecture that forms the foundation of WSL2, we will thoroughly explain all the steps to build the “ultimate development environment” demanded by professional engineers in a volume of over 10,000 characters. This covers settings to maximize performance, building a comfortable terminal environment, seamless integration with Docker and VS Code, and advanced network configurations.

1. WSL2 Architecture and Evolution from WSL1

To fully unleash the potential of WSL2, it is important to first understand its internal structure. The approach to running Linux binaries on Windows is fundamentally different between the first-generation WSL (WSL1) and WSL2.

WSL1: System Call Translation Layer

WSL1 adopted a mechanism that translates Linux system calls into Windows NT APIs in real-time. Because this did not use a virtual machine (VM), it had the advantage of very low resource overhead. However, it was difficult to perfectly emulate complex system calls, such as file system I/O operations, which led to devastating performance degradation, especially in processes dealing with large numbers of small files, such as Node.js npm install and Git repository operations.

WSL2: Lightweight Utility VM and a Complete Linux Kernel

In WSL2, the architecture was revamped, and an authentic Linux kernel built by Microsoft now runs directly on a “lightweight utility VM” utilizing a subset of the Hyper-V architecture. This ensures 100% compatibility for system calls and dramatically improves file I/O performance compared to WSL1 by using a virtual disk (VHDX) that utilizes the Linux-native ext4 file system.

The following Mermaid diagram shows the structural differences between WSL1 and WSL2.

flowchart TD
subgraph "Windows OS Environment"
A["Windows NT Kernel"]
A --> F["NTFS File System (C: Drive)"]
end
subgraph "WSL2 Architecture"
B["Hyper-V Hypervisor"]
B --> C["Lightweight Utility VM"]
C --> D["Linux Kernel (Microsoft)"]
D --> E["Ubuntu User Space (glibc, bash, etc.)"]
D --> G["ext4 Virtual Disk (.vhdx)"]
end
A -.->|"Plan 9 (9P) Protocol Network File Share"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

An important lesson to be learned from this structure is: “Access to files on the Linux side (inside the VHDX) is extremely fast, but access to files on the Windows side (/mnt/c/) is very slow because it goes through the 9P protocol.” The source code of your projects must always be placed under the home directory (~) on the WSL side.

2. Mathematical Analysis of Performance: Why is WSL2 so fast?

Let’s quantitatively evaluate the performance improvement of WSL2 using a mathematical model. One of the most time-consuming operations in software development is processing that involves a large amount of file I/O (e.g., library installation or building).

The total execution time $T_{total}$ of a certain process is expressed as the sum of the computing time by the CPU $T_{compute}$ and the time taken for disk I/O $T_{io}$.

$$ T_{total} = T_{compute} + T_{io} $$

In the case of WSL1, because an overhead occurs in translating Linux-side operations into NTFS operations, the I/O time is modeled as follows. Here, $n$ is the number of file operations, $t_{ntfs\_syscall}$ is the execution time of the Windows-side system call, and $t_{trans}$ is the overhead of the translation layer.

$$ T_{wsl1\_io} = \sum_{i=1}^{n} (t_{ntfs\_syscall_i} + t_{trans_i}) $$

On the other hand, in WSL2, since the kernel issues I/O directly to the ext4 file system, the overhead is only a very small delay $t_{virt}$ due to virtualization.

$$ T_{wsl2\_io} = \sum_{i=1}^{n} (t_{ext4_i} + t_{virt_i}) $$

In a general file system, since $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$, when $n$ is very large (performing tens to hundreds of thousands of file operations), the difference in I/O time between WSL1 and WSL2 grows exponentially.

Also, assuming the overhead ratio of CPU computation in a virtualized environment is $\rho$, with modern hardware-assisted virtualization (Intel VT-x / AMD-V), it stays around $\rho \approx 0.01 \sim 0.03$ (1 to 3%). Therefore, even in pure computational tasks, it delivers a performance of $97\% \sim 99\%$ which is comparable to a native Linux environment.

3. Installation and Foundation Building

On Windows 10/11, installing WSL2 has become very simple. Just open PowerShell with administrator privileges and run the following command.

1
2
3
4
5
6


# WSL2 and Ubuntu are installed by default
wsl --install

# When specifying a specific distribution
# You can check this with wsl --list --online
wsl --install -d Ubuntu-24.04

After installation, following a reboot, you will be prompted to set up a UNIX username and password upon the first launch. This user is independent of the Windows user and is only valid within WSL.

If you are already using WSL1, convert it to WSL2 with the following command.

1
2
3
4
5


# Convert an existing distribution to WSL2
wsl --set-version Ubuntu 2

# Set WSL2 as the default version for any future distributions you add
wsl --set-default-version 2

4. The Secret of Resource Control: .wslconfig and wsl.conf

One of the biggest traps in WSL2 is the “unlimited consumption of memory (bloating of the Vmmem process)”. Since WSL2 utilizes the Linux kernel’s page cache, it will endlessly consume the host’s (Windows) memory every time it performs I/O. To prevent this, it is essential to limit resources using configuration files.

WSL2 configuration files are divided into two: .wslconfig which affects the entire Windows system, and wsl.conf which affects the inside of each distribution.

4.1. .wslconfig (Windows side)

Create a file in the Windows user profile directory (C:\Users\<username>\.wslconfig) to control resource allocation for the VM.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# C:\Users\<username>\.wslconfig
[wsl2]
# Maximum memory allocated to the VM. We recommend about 50% to 75% of the host's total memory
memory=16GB

# Number of CPU cores to use (uses all cores if omitted)
processors=8

# Size of the swap file
swap=8GB

# Destination to save the swap file (useful if you want to save space on the C drive)
# swapfile=D:\\wsl\\swap.vhdx

# Enable localhost forwarding (to access WSL from the Windows side using localhost)
localhostForwarding=true

# Automatically free up memory (Windows 11 only)
# Dynamically releases page cache to prevent Vmmem bloating
autoMemoryReclaim=dropcache

[experimental]
# Advanced networking features available in Windows 11 22H2 and later
# This enables IPv6 support and allows sharing the same IP address between WSL and Windows
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Linux side)

Edit /etc/wsl.conf inside WSL to control the distribution-specific behavior.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# /etc/wsl.conf (edit inside WSL)
[network]
# Disable the automatic generation of /etc/resolv.conf when WSL starts
# Useful when you want to set your own DNS (e.g., 8.8.8.8)
generateResolvConf=false

# Set a custom hostname
hostname=WSL-DevNode

[automount]
# Settings for mounting Windows drives
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# Change the mount point of the C drive from /mnt/c to /c (to shorten the path)
root=/

[boot]
# Enable systemd (WSL 0.67.6 or later)
# This allows snaps and various daemons (like Docker) to run natively
systemd=true

[user]
# Default user to log in as
default=kenji

To apply these settings, you need to run wsl --shutdown in PowerShell to completely stop the WSL VM and then restart it.

5. The Ultimate Terminal Environment: Zsh + Powerlevel10k

Productivity won’t improve if you stick with the default bash. Combine Zsh, which boasts powerful completion features and visibility, with the ultra-fast theme “Powerlevel10k” to build the strongest prompt.

5.1. Installing and Configuring Windows Terminal

Install “Windows Terminal” from the Microsoft Store. Open the JSON settings (settings.json), set the default profile to WSL (Ubuntu), and change the font to a Nerd Font for development (e.g., HackGen Console NF or MesloLGS NF).

5.2. Installing Zsh and Oh My Zsh

Run the following commands in the WSL terminal.

1
2
3
4
5
6


# Update packages and install Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# Run the Oh My Zsh installation script
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. Introducing Powerlevel10k and Plugins

Introduce plugins that further enhance Zsh (syntax highlighting and auto-suggestions) and the Powerlevel10k theme.

1
2
3
4
5
6
7
8


# Powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

# zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

Edit ~/.zshrc to enable the theme and plugins.

1
2
3
4
5


# Changes in ~/.zshrc
ZSH_THEME="powerlevel10k/powerlevel10k"

# Add to the plugins array
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

After saving, running source ~/.zshrc will launch the Powerlevel10k configuration wizard (p10k configure). Follow the on-screen instructions to customize the prompt to your liking (prompt style, presence of icons, information to display, etc.). Information such as the Git branch name and status, Node.js version, and command execution time will be displayed in real-time, dramatically improving your development efficiency.

6. Seamless Integration with VS Code Remote - WSL

For development in WSL2, the “Remote - WSL” extension is the mechanism that seamlessly accesses files inside WSL from the IDE (Visual Studio Code) installed on the Windows side.

Architecture Explanation

The following sequence diagram shows how VS Code communicates with WSL2.

sequenceDiagram
autonumber
participant U as "Developer"
participant V as "VS Code UI (Windows)"
participant S as "VS Code Server (WSL2)"
participant F as "ext4 File System (WSL2)"
U->>V: "Type `code .` in WSL Terminal"
V->>S: "Establish RPC Connection via Vsock"
Note over V,S: Communicates via Hyper-V sockets without using TCP/IP
S->>F: "Read Source Files / Run Linter"
F-->>S: "Return Data & Analysis"
S-->>V: "Stream Language Server results to UI"
V-->>U: "Display syntax highlighting & errors"

The VS Code on the Windows side acts merely as a “thin client (UI)”, and heavy processing such as the Language Server, debugger, and terminal execution are all handled by the “VS Code Server” on the WSL side. This allows you to keep your environment clean on the WSL side without installing Node.js or Python on the Windows side.

Essential VS Code Settings

Install “WSL” (ms-vscode-remote.remote-wsl) from the “Extensions” in VS Code. After that, simply navigate to your project directory in the WSL terminal and run code ., which will launch the Windows-side VS Code with that directory open.

Important Note (Line Ending Issue): Windows and Linux have different line endings (Windows uses CRLF, while Linux uses LF). When developing on WSL, be sure to unify Git’s core.autocrlf setting and VS Code’s default file setting to LF. Neglecting this will cause you to suffer from mysterious errors when executing shell scripts or Docker containers.

1
2


# Git line ending setting on the WSL side
git config --global core.autocrlf input

Also add the following to VS Code’s settings.json (remote settings).

1
2
3
4


{
 "files.eol": "\n",
 "terminal.integrated.defaultProfile.linux": "zsh"
}

7. Optimizing Docker Desktop and WSL2 Integration

There are mainly two approaches to using Docker in a WSL2 environment:

Install Docker Desktop for Windows and enable the WSL2 integration feature.
Directly install native Docker Engine inside WSL2 (e.g., Ubuntu).

Approach 1: Docker Desktop (Recommended)

This is recommended in most cases because it is easy to manage via a GUI and allows transparent access to containers between Windows and WSL. Check the following in the Docker Desktop settings (Settings):

Check General -> Use the WSL 2 based engine.
Check Resources -> WSL Integration -> Enable integration with my default WSL distro, and turn on the toggle button for the distribution you use (Ubuntu).

This allows you to execute the docker command directly from the WSL2 terminal, and communication with the Docker daemon is done through dedicated lightweight VMs (docker-desktop and docker-desktop-data) managed by Docker Desktop.

Approach 2: Direct Installation of Native Docker Engine

If there are corporate network restrictions (like avoiding paid Docker Desktop plans) or if you want to minimize performance overhead to the limit, enable systemd in /etc/wsl.conf and install Docker as a pure Ubuntu server.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# Excerpt of the official Docker installation steps on WSL2 Ubuntu with systemd enabled
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
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 repository
echo \
 "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
 "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

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

# Add the current user to the docker group (to execute without sudo)
sudo usermod -aG docker $USER

After a reboot, systemctl start docker will function exactly like a native Linux environment and deliver high performance.

8. SSH Key Integration: Seamless Authentication between Windows and WSL

Managing separate SSH keys on the Windows side and the WSL side when doing Git SSH cloning or SSH connecting to remote servers is extremely tedious. To balance security and convenience, configure a bridge for the SSH agent running on the Windows side (or a password manager like 1Password) to the WSL side.

Here, we will explain the most secure and modern approach: using the 1Password SSH Agent feature or the Windows OpenSSH Authentication Agent, and forwarding it to a UNIX domain socket in WSL2 using npiperelay or socat.

Socket Forwarding for ssh-agent

You need to convert the SSH agent typically provided as a Named Pipe in Windows into a socket file on the WSL side. This is easy if you use wsl-ssh-agent or the features provided by 1Password.

From the 1Password settings screen, enable “Developer” -> “Use SSH agent”. Next, add the following configuration to ~/.zshrc or ~/.bashrc on the WSL side so that it automatically binds to the socket upon login.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Addition to ~/.zshrc (Example when using 1Password SSH Agent)
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# If the socket doesn't exist at WSL startup, or the process isn't bound, forward using socat and npiperelay
ALREADY_RUNNING=$(ps -aux | grep "[n]piperelay.exe -ei -s //./pipe/openssh-ssh-agent" | wc -l)
if [ $ALREADY_RUNNING -eq 0 ]; then
 if [ -S $SSH_AUTH_SOCK ]; then
 rm $SSH_AUTH_SOCK
 fi
 # Launch socat in the background to connect the Windows-side Named Pipe to the WSL-side UNIX socket
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

Note: You must install npiperelay.exe on the Windows side and add it to your PATH beforehand.

Once this setup is complete, when you run ssh-add -l from the WSL terminal, a list of public keys for the SSH keys registered in 1Password or on the Windows side will be displayed. This allows you to securely pass authentication without copying your private key files into WSL.

9. Maintenance: Optimizing (Compacting) the Bloated VHDX

One of the biggest drawbacks of WSL2 is its behavior where “the file size of the virtual disk (.vhdx) on the Windows side is not automatically reduced even when Docker images or files are deleted”. If you continue developing for a long time, the ext4.vhdx file will swell to tens or hundreds of gigabytes.

To free up disk space, you need to regularly optimize (Compact) the VHDX from the Windows side.

First, completely shut down WSL.
1

wsl --shutdown
Open PowerShell with administrator privileges and run the following diskpart command, or the Optimize-VHD command of the Hyper-V module (the latter can only be used if Hyper-V is enabled).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# When the Hyper-V module is available
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# When using diskpart
diskpart
# Enter interactively in the following prompt
DISKPART> select vdisk file="C:\Users\<username>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

By performing this operation regularly, you can reclaim unnecessarily consumed space on your C drive.

10. Conclusion

WSL2 has completely transcended the framework of being just a “bonus Linux running on Windows” and has evolved into a powerful development platform that is equal to, or even better than, MacOS and native Linux machines.

By applying all the configurations explained here (resource optimization via .wslconfig, terminal enhancement with Zsh + Powerlevel10k, transparent access with VS Code Remote, and SSH integration and VHDX maintenance), a stress-free, fast, and secure “ultimate development environment” is completed.

Although setting up the environment takes a little effort, once the settings are solidified, there is no doubt that your future engineering productivity will improve dramatically. Please explore further customizations based on this guide to suit your projects and preferences.