Common WSL Configuration Notes

Network Modes

WSL 2 primarily has two common network modes: NAT and mirrored. By default, WSL 2 uses NAT mode.

Mirrored

mirrored can be understood as a mirrored network mode. When enabled, WSL tries to mirror Windows' network interfaces, placing WSL and Windows in a closer network semantic.

The experience feels more like:

• The network behavior of WSL and Windows is more aligned;
• WSL can more conveniently use the network environment on Windows;
• Compatibility is generally better under complex network environments like VPNs, corporate proxies, and network policies.

Common advantages:

• Supports IPv6;
• Services listening on Windows can be accessed via 127.0.0.1 from within WSL;
• Better VPN compatibility;
• Supports multicast;
• Other devices on the local network can access services running in WSL more directly.

Note that mirrored requires Windows 11 22H2 or later. If the system version is lower, the configuration might not take effect even if written.

NAT

NAT is the default network mode for WSL 2.

In this mode, the Windows host acts like a router, and WSL runs in an independent virtual subnet.

Typical characteristics:

• WSL will have an independent private IP, such as 172.x.x.x or 20.x.x.x;
• WSL initiating outbound connections generally works fine;
• External devices accessing services in WSL usually require additional port forwarding configuration;
• The Windows host can access ports listening in WSL via localhost:PORT.

In NAT mode, if a program in WSL listens on a port and localhostForwarding is not disabled, Windows can usually access that service via localhost on the same port.

For example, if a web service is started in WSL:

python3 -m http.server 3000

Then the Windows side can generally access:

http://localhost:3000

To allow other devices on the local network to access services in WSL, you typically need to configure port forwarding or switch to mirrored network mode.

File System

Windows disks are mounted under the /mnt directory in WSL:

• C: → /mnt/c
• D: → /mnt/d

WSL distributions are also exposed as UNC paths in Windows. For example, the root directory / of the Ubuntu Linux file system can usually be accessed via the following path:

\\wsl$\Ubuntu\

On newer versions of Windows, you might also see a path like:

\\wsl.localhost\Ubuntu\

General recommendations:

• If working on the Linux command line, keep project files in WSL's Linux file system;
• If working with Windows tools, keep project files in the Windows file system;
• Avoid frequent cross-file-system reads and writes of project files whenever possible.

For example, when developing Node.js, Go, Rust, or Python projects in WSL, it's better to place the project in:

/home/<username>/projects

Rather than:

/mnt/c/Users/<username>/Desktop

This usually reduces issues related to permissions, performance, and file watching.

Environment Variables and Interoperability

When WSL starts, it injects some Windows environment variables, especially Path.

By default, WSL converts the Windows Path into /mnt-style paths and appends them to the Linux $PATH. Therefore, some Windows programs can be called directly from within WSL.

For example:

notepad.exe
explorer.exe .
code .

WSL can also directly run Windows .exe programs. In most cases, WSL automatically converts between Linux paths and Windows paths.

For example, executing this in WSL:

explorer.exe .

Opens the current directory directly in Windows File Explorer.

However, if interoperability is disabled or Windows Path injection is turned off, these behaviors will be affected.

Configuration Files

WSL mainly has two types of configuration files:

1. The global configuration file on the Windows side: C:\Users<username>.wslconfig
2. The configuration file inside the WSL distribution: /etc/wsl.conf

Their scopes differ.

.wslconfig affects all WSL 2 distributions and is mainly used to configure the WSL 2 virtual machine itself, such as network mode, memory, CPU, proxy, port forwarding, etc.

/etc/wsl.conf only affects the current distribution and is mainly used to configure the behavior of the current Linux distribution, such as the default user, whether to mount Windows disks, whether to enable systemd, whether to allow calling Windows programs, etc.

Windows-Side Configuration: .wslconfig

.wslconfig is located in the Windows user directory:

C:\Users\<username>\.wslconfig

Example of common configuration:

[wsl2]
networkingMode=mirrored
autoProxy=true
localhostForwarding=false

networkingMode

networkingMode configures the network mode for WSL 2.

Common values include:

networkingMode=nat

Or:

networkingMode=mirrored

Where:

• nat is the default mode;
• mirrored is the mirrored network mode;
• bridged is no longer recommended.

If you need better support for VPNs, LAN access, IPv6, or multicast, try using:

networkingMode=mirrored

autoProxy

autoProxy controls whether to automatically inject Windows HTTP proxy information into WSL.

For example:

autoProxy=true

If Windows has a system proxy configured, enabling this will make WSL attempt to automatically use Windows' proxy information.

However, if your proxy software only listens on Windows' local 127.0.0.1, in NAT mode WSL might not be able to use that proxy directly. This is because 127.0.0.1 inside WSL points to WSL itself, not the Windows host.

In this case, consider:

• Disabling autoProxy and setting the proxy address manually;
• Changing the proxy address to a Windows host address accessible from WSL;
• Enabling "Allow LAN connections" in your proxy software;
• Using the TUN mode of your proxy software;
• Switching to mirrored network mode.

localhostForwarding

localhostForwarding controls whether ports listening in WSL 2 can be accessed via the Windows host's localhost:PORT.

For example:

localhostForwarding=true

It is enabled by default.

In NAT mode, if a service is started in WSL:

npm run dev

And listens on:

0.0.0.0:3000

Or:

127.0.0.1:3000

Then Windows can generally access it via:

http://localhost:3000

If set to:

localhostForwarding=false

Then accessing WSL services from Windows via localhost might stop working.

Note that in mirrored mode, localhostForwarding is ignored.

WSL-Side Configuration: /etc/wsl.conf

/etc/wsl.conf is located inside the WSL distribution:

/etc/wsl.conf

Example of common configuration:

[boot]
systemd=true

[user]
default=ruqiu

[interop]
enabled=false
appendWindowsPath=false

[automount]
enabled=true
root=/mnt

boot.systemd

boot.systemd sets whether to enable systemd.

[boot]
systemd=true

When enabled, WSL uses systemd as PID 1 on startup. This provides an experience closer to a standard Linux distribution and makes it easier to use services that depend on systemd.

For example:

systemctl status

If systemd is enabled, many systemctl related commands will work normally.

However, enabling systemd might make WSL startup slightly slower than the minimal mode.

user.default

user.default sets the default login user.

[user]
default=ruqiu

After setting this, opening the WSL distribution directly from Windows will default to the ruqiu user.

This is roughly equivalent to:

wsl -u ruqiu

If not set, WSL typically uses the user created during the distribution's initial setup.

interop.enabled

interop.enabled controls the interoperability between WSL and Windows.

[interop]
enabled=false

When disabled, Windows .exe programs cannot be called directly from within WSL.

For example, these commands might stop working:

notepad.exe
explorer.exe .
code .

If you don't want WSL to call Windows programs, you can disable this.

interop.appendWindowsPath

interop.appendWindowsPath controls whether to inject the Windows Path into WSL's $PATH.

[interop]
appendWindowsPath=false

When disabled, the Windows PATH is no longer automatically appended to WSL.

Note that enabled and appendWindowsPath are two different settings.

Even if:

enabled=true

But if:

appendWindowsPath=false

Then WSL still supports calling Windows programs, but can no longer rely on PATH to automatically find these .exe files. You would need to specify the full path manually.

automount.enabled

automount.enabled controls whether to automatically mount Windows disks.

[automount]
enabled=true

By default, Windows disks are automatically mounted under /mnt.

For example:

/mnt/c
/mnt/d

If set to:

[automount]
enabled=false

Then Windows disks will not be automatically mounted in WSL.

However, this only affects whether Windows disks are mounted inside WSL; it does not affect Windows accessing the WSL file system via \wsl$ or \wsl.localhost.

automount.root

automount.root sets the mount point for Windows disks inside WSL.

The default location is:

root=/mnt

Resulting in mounts like:

C: -> /mnt/c
D: -> /mnt/d

If changed to:

root=/

The mount results might become:

C: -> /c
D: -> /d

Generally, keeping the default /mnt is fine.

Applying Configuration

After modifying .wslconfig or /etc/wsl.conf, you need to restart WSL for the configuration to take effect.

You can execute this in PowerShell:

wsl --shutdown

Then reopen WSL.

You can also check if any distributions are currently running:

wsl --list --running

If you only want to shut down a specific distribution, use:

wsl --terminate <distribution-name>

For example:

wsl --terminate Ubuntu

Summary

In short:

• .wslconfig is the global WSL 2 configuration on the Windows side;
• /etc/wsl.conf is the configuration inside a single WSL distribution;
• NAT is the default network mode for WSL 2;
• mirrored is more suitable for scenarios involving VPNs, LAN access, IPv6, multicast, etc.;
• Windows disks are mounted by default to paths like /mnt/c, /mnt/d;
• The WSL file system can be accessed from Windows via \wsl$ or \wsl.localhost;
• After modifying the configuration, you need to run wsl --shutdown or wait for WSL to fully exit and restart.