Skip to content
Fernando Valler

A Practical WSL2 Setup: Configuration Tips I Use for Development

A few simple settings can make WSL2 much more predictable and comfortable for development. In this guide, I share the configuration I commonly use for memory, CPU, swap, systemd, networking, hosts, and file permissions.

A Practical WSL2 Setup: Configuration Tips I Use for Development

WSL2 already works very well with its default settings, but a few adjustments can make a noticeable difference when it becomes part of your daily development environment.

For developers working with PHP, Node.js, Docker, databases, local servers, and Linux tooling, it is especially useful to understand two configuration files:

  • .wslconfig
  • /etc/wsl.conf

They serve different purposes, and understanding that difference avoids a lot of confusion.

.wslconfig vs /etc/wsl.conf

The .wslconfig file controls global WSL2 settings and is stored in the Windows user profile:

text
C:\Users\YOUR_USER\.wslconfig

The /etc/wsl.conf file controls configuration for a specific Linux distribution:

text
/etc/wsl.conf

In practice:

FileScopeExamples
.wslconfigGlobal WSL2 settingsMemory, CPU, swap, networking
wsl.confPer-distribution settingssystemd, automount, hosts, user

This distinction matters because configuration examples often mix settings from both files.

1. Limiting memory and processors

In my .wslconfig, one setting I find useful is explicitly limiting the resources available to WSL:

ini
[wsl2]

memory=16GB
processors=8
swap=2GB

The goal is not simply to give Linux as many resources as possible.

WSL shares the host machine’s resources with Windows and other applications. Explicit limits can make the development environment more predictable, especially when several heavy applications are running at the same time.

memory

ini
memory=16GB

This defines the memory limit for the virtual machine used by WSL2.

The right value depends on the amount of RAM available on the host and on the type of development work you do.

For example, you may have:

  • an IDE;
  • a browser;
  • Docker;
  • databases;
  • AI tools;
  • Linux services;
  • Windows applications.

There is no universal value that works for every machine.

processors

ini
processors=8

This defines how many logical processors can be used by the WSL2 VM.

On machines with many CPU cores, setting a limit can help prevent Linux workloads from consuming every available processor.

swap

ini
swap=2GB

This defines the amount of swap space used by WSL2.

Swap does not replace RAM, but it provides an additional layer of memory when physical memory becomes insufficient.

I prefer keeping a relatively small swap size on a development machine, although the right value depends on the workload.

2. Mirrored networking mode

Another setting I keep available, but do not always enable, is:

ini
[wsl2]

networkingMode=mirrored

The mirrored mode changes the networking architecture used by WSL2 so that Windows network interfaces are mirrored into Linux.

According to Microsoft’s documentation, benefits include IPv6 support, improved VPN compatibility, multicast support, and direct LAN access to WSL in appropriate scenarios.

Because of that, I usually leave the option commented out:

ini
# networkingMode=mirrored

This makes it easy to enable when needed.

The setting can be particularly interesting when working with:

  • corporate VPNs;
  • multiple network interfaces;
  • local services that need to be reached from other devices;
  • environments where the default WSL NAT networking causes limitations.

It is still worth enabling it only when your environment actually needs it.

3. Enabling systemd

This setting belongs in /etc/wsl.conf inside the Linux distribution:

ini
[boot]
systemd=true

Systemd becomes useful when Linux services need to behave more like they would on a traditional Linux installation.

For example:

bash
systemctl status

or:

bash
systemctl list-unit-files --type=service

This can simplify environments that depend on services such as:

  • Docker;
  • databases;
  • Redis;
  • background services;
  • other applications that use systemd.

After changing wsl.conf, the WSL instance usually needs to be restarted.

From Windows:

powershell
wsl --shutdown

Then start the distribution again.

4. Keeping a custom /etc/hosts

Another setting I like is:

ini
[network]
generateHosts=false

By default, WSL can automatically generate /etc/hosts.

Disabling that behavior allows the distribution to keep its own hosts file instead.

This is useful when working with several local development domains.

For example:

text
127.0.0.1 app.local
127.0.0.1 api.local
127.0.0.1 admin.local

This can be useful for development environments with:

  • multiple applications;
  • reverse proxies;
  • virtual hosts;
  • Traefik;
  • Apache;
  • Nginx;
  • custom local domains.

5. File permissions on /mnt

This is another setting that can make a difference when working with Windows files from Linux.

By default, WSL mounts Windows drives under:

text
/mnt/c
/mnt/d

using DrvFs.

In /etc/wsl.conf, additional mount options can be configured:

ini
[automount]
options="metadata"

The metadata option allows Linux permission metadata to be stored for Windows files mounted through WSL.

This is useful when Linux tools depend on file permissions.

6. Using umask and fmask

Another option is:

ini
[automount]
options="metadata,umask=022,fmask=011"

These masks control which permissions are removed from files and directories.

For example:

text
umask=022

is a common configuration that usually results in directory permissions behaving similarly to:

text
755

fmask can then be used to apply an additional mask specifically to files.

The important difference is:

  • umask affects files and directories;
  • fmask affects files;
  • dmask can be used specifically for directories.

These permission masks are documented by Microsoft as part of the DrvFs automount options.

One important detail

Do not create multiple [automount] sections in the same file as two different examples found online.

Use a single section:

ini
[automount]
options="metadata,umask=022,fmask=011"

Or, if you do not need the masks:

ini
[automount]
options="metadata"

These are alternatives.

7. My base configuration

When the settings are correctly split between the two files, a configuration close to what I use looks like this.

%UserProfile%\.wslconfig

ini
[wsl2]

memory=16GB
processors=8
swap=2GB

# Enable when it makes sense for your networking environment
# networkingMode=mirrored

/etc/wsl.conf

ini
[boot]
systemd=true

[network]
generateHosts=false

[automount]
options="metadata,umask=022,fmask=011"

Keeping these files separate makes it much easier to understand which settings are global WSL2 options and which settings belong to a specific Linux distribution.

8. An important performance detail

There is another setting that I consider even more important than many .wslconfig options: where project files are stored.

When most development tools run inside Linux, I prefer keeping projects in the Linux filesystem:

text
/home/fernando/projects

instead of:

text
/mnt/c/Users/Fernando/projects

Microsoft recommends storing files on the same operating system as the tools that access them most frequently.

For example, Linux tools such as:

bash
git
npm
composer
php
make

usually perform better when the project is stored in the Linux filesystem.

The difference becomes particularly noticeable in projects with many files, such as:

text
node_modules
vendor
.git
cache
build

When I need to access the files from Windows Explorer, I can simply run:

bash
explorer.exe .

That lets me keep the files inside the Linux filesystem without giving up Windows integration.

9. Applying configuration changes

After changing .wslconfig or /etc/wsl.conf, simply closing the terminal window may not be enough.

A practical way to restart WSL is:

powershell
wsl --shutdown

Then:

powershell
wsl

You can also check whether any distributions are still running:

powershell
wsl --list --running

This matters because configuration changes only take effect after the WSL instance has fully stopped and restarted.

10. Checking the configuration

After restarting, I like to quickly verify the environment.

Memory

bash
free -h

CPUs

bash
nproc

Systemd

bash
systemctl is-system-running

Mounts

bash
mount | grep /mnt

Installed distributions

From Windows:

powershell
wsl --list --verbose

WSL version

powershell
wsl --version

These checks help distinguish configuration problems from issues related to the WSL version itself.

11. What is actually worth configuring?

There is no universal WSL2 configuration.

My approach is to start with the minimum required settings and add more only when the development environment actually needs them.

I usually think about four categories.

Resources

ini
memory=16GB
processors=8
swap=2GB

Linux services

ini
[boot]
systemd=true

Networking

ini
[network]
generateHosts=false

or:

ini
networkingMode=mirrored

Files

ini
[automount]
options="metadata,umask=022,fmask=011"

The goal is not to have the largest possible configuration file.

The goal is to have a predictable development environment.

Conclusion

WSL2 works very well with its defaults, but understanding its configuration files gives you much more control over the environment.

For me, the most useful areas are:

  • controlling how much CPU and memory WSL can use;
  • enabling systemd when Linux services need it;
  • controlling how /etc/hosts is managed;
  • adjusting permissions for Windows drives mounted inside Linux;
  • enabling mirrored networking when the default NAT architecture is not enough;
  • keeping projects in the Linux filesystem when the main development tools run inside WSL.

More importantly, the goal should not be to copy someone else’s configuration blindly.

The best .wslconfig is the one that matches your machine and your development workflow.