How to Configure the .wslconfig File in Windows 11 to Optimise WSL2 Memory and CPU Usage

Windows Subsystem for Linux (WSL2) runs a genuine Linux kernel inside a lightweight virtual machine utility VM managed by Hyper-V. By default, WSL2 dynamically allocates up to 50% of your total system RAM (or 8GB, whichever is less on older builds, and often up to 50% on newer Windows 11 releases) and all available CPU logical cores. In resource-intensive workloads such as compiling large codebases, running Docker containers, or training local machine learning models, WSL2 can consume excessive host memory, leading to sluggish host performance. Creating and tailoring the global .wslconfig file gives you complete control over resource limits.

Understanding the Difference Between wsl.conf and .wslconfig

Windows provides two separate configuration files for managing WSL environments:

• /etc/wsl.conf: Located inside the Linux filesystem of a specific distribution. It manages distribution-level preferences such as default user accounts, automount options, and network resolution.
• %UserProfile%\.wslconfig: Located in your Windows user profile root. It applies globally across all WSL2 distributions and controls virtual machine hardware resource allocation (RAM limits, CPU core limits, swap files, and localhost proxying).

Step 1: Locate and Create the .wslconfig File

The .wslconfig file does not exist by default on fresh Windows 11 installations. You must create it in your personal user home directory:

1. Press Win + R to launch the Run dialogue box.
2. Type %UserProfile% and press Enter to open your user home folder (typically C:\Users\<YourUsername>\).
3. Right-click inside the directory, select New > Text Document, and name the file .wslconfig. Ensure you remove the .txt extension.
4. Alternatively, launch PowerShell as a standard user and generate the file directly:

   New-Item -Path "$env:USERPROFILE\.wslconfig" -ItemType File -Force
   notepad "$env:USERPROFILE\.wslconfig"

Step 2: Define Core WSL2 Hardware Allocations

Open .wslconfig in Notepad or your preferred text editor and structure the configuration under the [wsl2] section header. Below is an optimal starting template for a developer system with 16GB or 32GB of total host RAM:

[wsl2]
# Restrict WSL2 to allocate a maximum of 8GB of system RAM
memory=8GB

# Allocate 4 logical processor cores to the virtual machine
processors=4

# Set virtual swap space to 4GB (stored on an SSD)
swap=4GB

# Specify a custom location for the swap file (optional)
# swapFile=C:\\temp\\wsl-swap.vhdx

# Enable localhost forwarding to connect to Linux servers via localhost in Windows browsers
localhostForwarding=true

# Automatically release cached memory back to the host operating system
autoMemoryReclaim=gradual

Step 3: Advanced Windows 11 WSL2 Configuration Directives

Windows 11 introduces advanced virtualization and networking flags that enhance developer agility and conserve laptop battery:

Automated Memory Reclaim

When Linux processes terminate, page cache memory often remains assigned to the VM. In modern Windows 11 builds, set autoMemoryReclaim to reclaim unused pages automatically:

# Options: disabled, gradual, dropcache
autoMemoryReclaim=gradual

The gradual setting progressively releases dormant memory back to Windows without incurring CPU spikes, while dropcache aggressively dumps cached disk pages.

Mirrored Networking Mode

Traditional WSL2 networking relies on virtual NAT, which can complicate VPN connections and local development servers. Windows 11 includes a modern mirrored networking stack:

[experimental]
autoMemoryReclaim=gradual
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

The mirrored mode mirrors host network interfaces directly into Linux, resolving long-standing VPN compatibility issues and enabling seamless IPv6 support.

Step 4: Restart WSL2 to Apply the Configuration

Changes made to .wslconfig take effect only after shutting down the WSL2 Hyper-V microVM entirely:

1. Open a standard PowerShell or Command Prompt terminal.
2. Issue the explicit shutdown command:

   wsl --shutdown

3. Wait approximately five seconds to ensure all background Hyper-V instances terminate.
4. Launch your preferred Linux distribution (e.g. Ubuntu):

   wsl

Step 5: Verify Hardware Resource Limits in Linux

Once inside your Linux shell, verify that the resource limits defined in .wslconfig are actively enforced by the Linux kernel:

Check Allocated Memory and Swap

free -h

The total memory figure should correspond closely to the memory= limit defined in your configuration file.

Check Allocated Processor Cores

nproc
lscpu | grep "CPU(s):"

The reported core count will match the processors= integer specified in your settings.

Troubleshooting Common WSL2 Resource Issues

If WSL2 fails to launch after editing .wslconfig, verify that the file is saved using UTF-8 encoding without a Byte Order Mark (BOM) and contains no duplicate section headers. Ensure that numeric allocations include proper units (such as GB or MB) without spaces. If unexpected memory growth occurs during heavy Docker builds, check that Docker Desktop is set to use the WSL2 backend rather than independent Hyper-V machines.