WSL2 Proxy Configuration Guide – Complete (2026)

WSL2 proxy configuration guide is essential for developers and IT professionals who need to route traffic through a proxy server when using Windows Subsystem for Linux 2. Whether you’re behind a corporate firewall, using a VPN, or running a local proxy tool like Clash or Charles, configuring WSL2 to use your Windows proxy can be challenging due to the virtualized networking layer. According to Microsoft’s WSL troubleshooting documentation, WSL2 uses a virtualized network adapter with its own IP address, which means proxy settings from Windows do not automatically carry over to your Linux environment. This comprehensive WSL2 proxy configuration guide covers 10 proven methods to configure proxies and restore connectivity.

When you search for a WSL2 proxy configuration guide, you are likely dealing with a scenario where curl google.com hangs, sudo apt update fails with connection errors, or git clone times out. According to a detailed Windows Forum guide, the root cause is that WSL2 runs behind a host-based NAT, creating a virtualized network interface that insulates the Linux instance from the Windows host[reference:0]. This WSL2 proxy configuration guide walks you through every method needed to bridge that gap.

1. Understanding WSL2 Proxy Configuration

WSL2 uses a lightweight virtual machine with its own virtual network adapter and a NAT (Network Address Translation) topology[reference:3]. This architectural shift gives you a real Linux kernel but also creates a network barrier between Windows and WSL2:

• NAT isolation: WSL2 has its own private IP address space behind NAT[reference:4].
• localhost asymmetry: 127.0.0.1 in WSL2 points to the Linux VM itself, not the Windows host[reference:5].
• No proxy inheritance: Windows proxy settings are not automatically passed to WSL2.
• VPN conflicts: Enterprise VPNs that modify the Windows network stack can break WSL2 connectivity[reference:6].

According to a CSDN guide, when your proxy software runs on Windows and listens on 127.0.0.1, WSL2 cannot reach it because localhost in WSL2 is not the same as localhost on Windows[reference:7]. This WSL2 proxy configuration guide helps you overcome these challenges.

2. WSL2 Proxy Configuration Guide: Mirrored Networking Mode

Mirrored Networking mode is the recommended WSL2 proxy configuration method for Windows 11 22H2 and later. According to a detailed guide, mirrored mode “mirrors” your Windows network interfaces into the Linux VM, meaning WSL2 shares the same IP as the host and can access 127.0.0.1 directly[reference:8][reference:9].

Step 1: Open a text editor to create .wslconfig:
    notepad %USERPROFILE%\.wslconfig

Step 2: Add the following configuration:
    [wsl2]
    networkingMode=mirrored

Step 3: Save and close the file

Step 4: Restart WSL:
    wsl --shutdown

Step 5: Open your WSL terminal and verify:
    curl -x http://127.0.0.1:7890 -s https://github.com -o /dev/null -w "%{http_code}"
    # Should return 200 if successful[reference:10]

According to a GitHub guide, mirrored mode allows WSL2 to directly use the Windows proxy on 127.0.0.1 without additional configuration[reference:11].

Mirrored networking also gives you IPv6 support, better VPN compatibility, and the ability to reach WSL2 services directly from your LAN[reference:12].

Outcome: WSL2 shares the Windows network stack, enabling direct proxy access.

3. WSL2 Proxy Configuration Guide: Auto Proxy

The autoProxy setting is a powerful WSL2 proxy configuration feature that automatically propagates Windows proxy settings into WSL2. According to Microsoft’s documentation, when enabled, WSL propagates Windows HTTP proxy information into Linux environment variables like HTTP_PROXY and HTTPS_PROXY[reference:13].

Step 1: Open or create .wslconfig:
    notepad %USERPROFILE%\.wslconfig

Step 2: Add autoProxy to the configuration:
    [wsl2]
    networkingMode=mirrored
    [experimental]
    autoProxy=true[reference:14]

Step 3: Save and close the file

Step 4: Restart WSL:
    wsl --shutdown

Step 5: Reopen your WSL terminal and check:
    echo $HTTP_PROXY
    echo $HTTPS_PROXY

According to a CSDN guide, enabling autoProxy automatically sets the proxy environment variables[reference:15].

According to the Windows Forum guide, autoProxy=true tells WSL to adopt Windows’ HTTP proxy settings automatically[reference:16]. This simplifies WSL2 proxy configuration significantly.

Outcome: Windows proxy settings are automatically applied to WSL2.

4. WSL2 Proxy Configuration Guide: NAT Mode with Gateway IP

If you’re on Windows 10 or cannot use Mirrored Networking for any reason, the NAT mode approach using the WSL gateway IP is the recommended WSL2 proxy configuration method. According to a guide from Imsxx, WSL2 default is NAT — WSL2 won’t automatically use Windows 127.0.0.1 proxy[reference:17].

Step 1: Find the WSL gateway IP (the Windows host address inside WSL):
    cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
    # Example output: 172.20.0.1[reference:18]

Step 2: Set the proxy environment variables in your WSL terminal:
    export http_proxy="http://172.20.0.1:7890"
    export https_proxy="http://172.20.0.1:7890"
    export all_proxy="socks5://172.20.0.1:7890"[reference:19]

Step 3: Test the connection:
    curl -I https://www.google.com[reference:20]

According to a CSDN guide, this is the most reliable approach for NAT mode[reference:21].

You can also configure your Windows proxy software to listen on 0.0.0.0 instead of 127.0.0.1, but this exposes the proxy to your entire LAN[reference:22].

Outcome: WSL2 uses the Windows host IP to route proxy traffic through NAT.

5. Set HTTP/S Environment Variables

Setting the HTTP_PROXY and HTTPS_PROXY environment variables is the foundation of WSL2 proxy configuration. According to a guide from Datasea.cn, many tools respect these variables[reference:23].

For NAT mode (using gateway IP):
    export http_proxy="http://172.20.0.1:7890"
    export https_proxy="http://172.20.0.1:7890"

For Mirrored mode (using localhost):
    export http_proxy="http://127.0.0.1:7890"
    export https_proxy="http://127.0.0.1:7890"

For socks5 proxies:
    export all_proxy="socks5://127.0.0.1:7890"

To check if your proxy is set:
    env | grep -i proxy

According to a Superuser guide, these environment variables affect TCP connections (curl/apt/git)[reference:24].

This WSL2 proxy configuration method works for most command-line tools including curl, wget, and npm.

Outcome: HTTP/S traffic from your WSL2 terminal is routed through the proxy.

6. Configure APT Proxy

APT requires special handling for WSL2 proxy configuration because sudo clears environment variables by default. According to a Debian guide, APT has its own configuration system and does not automatically inherit shell http_proxy[reference:25].

Method 1: APT configuration file (recommended persistent config)
Step 1: Create the APT proxy configuration:
    sudo nano /etc/apt/apt.conf.d/proxy.conf

Step 2: Add the following lines (adjust port for your proxy):
    Acquire::http::Proxy "http://127.0.0.1:7890";
    Acquire::https::Proxy "http://127.0.0.1:7890";[reference:26]

Step 3: Save and exit (Ctrl+X, Y, Enter)

Step 4: Test APT:
    sudo apt update[reference:27]

Method 2: Temporary command-line proxy (for one-time use):
    sudo apt -o Acquire::http::Proxy="http://127.0.0.1:7890" update[reference:28]

Method 3: Preserve environment with sudo -E:
    export http_proxy="http://127.0.0.1:7890"
    sudo -E apt update[reference:29]

Method 4: Preserve environment via sudoers (persistent fix):
    sudo visudo
    Add: Defaults env_keep += "http_proxy https_proxy no_proxy HTTP_PROXY HTTPS_PROXY NO_PROXY"[reference:30]

According to a guide from Zedware, this is the most bulletproof approach for APT[reference:31].

Outcome: APT can download packages through the proxy.

7. Configure Git Proxy

Git needs separate WSL2 proxy configuration for HTTP and SSH connections. According to a Juejin guide, WSL2 can directly reuse the host’s proxy[reference:32].

HTTP/HTTPS Git proxy:
Step 1: Set the Git proxy globally:
    git config --global http.proxy http://127.0.0.1:7890
    git config --global https.proxy http://127.0.0.1:7890[reference:33]

Step 2: Verify the configuration:
    git config --global --get http.proxy

Step 3: To unset the proxy:
    git config --global --unset http.proxy
    git config --global --unset https.proxy[reference:34]

SSH Git proxy (git clone git@github.com:user/repo.git):
Step 1: Install connect-proxy:
    sudo apt update && sudo apt install connect-proxy[reference:35]

Step 2: Configure SSH to use the proxy:
    nano ~/.ssh/config

Step 3: Add these lines:
    Host github.com
        User git
        ProxyCommand connect -H 127.0.0.1:7890 %h %p[reference:36]

Step 4: Secure the config file:
    chmod 600 ~/.ssh/config[reference:37]

Note: If using SOCKS5, replace -H with -S[reference:38]

Outcome: Git operations (clone, push, pull) work through the proxy.

8. Configure SSH Proxy with connect-proxy

SSH connections (including git clone git@...) cannot use HTTP_PROXY directly. According to a guide from Zedware, SSH handles proxy routes entirely differently[reference:39].

Step 1: Install the connect-proxy tool:
    sudo apt install connect-proxy

Step 2: Configure SSH:
    nano ~/.ssh/config

Step 3: Add this template (replace port with your proxy port):
    Host *
        ProxyCommand connect -H 127.0.0.1:7890 %h %p

For a specific host (e.g., github.com):
    Host github.com
        User git
        ProxyCommand connect -H 127.0.0.1:7890 %h %p[reference:40]

Step 4: Set proper permissions:
    chmod 600 ~/.ssh/config

Step 5: Test SSH connection:
    ssh -T git@github.com

Note: If using SOCKS5, use connect -S instead of connect -H[reference:41]

Outcome: SSH and SSH-based Git operations work through the proxy.

9. Configure npm and yarn Proxy

Node.js package managers also need WSL2 proxy configuration for proper functionality.

npm proxy configuration:
Step 1: Set npm proxy:
    npm config set proxy http://127.0.0.1:7890
    npm config set https-proxy http://127.0.0.1:7890

Step 2: Unset npm proxy:
    npm config delete proxy
    npm config delete https-proxy

yarn proxy configuration:
Step 1: Set yarn proxy:
    yarn config set proxy http://127.0.0.1:7890
    yarn config set https-proxy http://127.0.0.1:7890

Step 2: Unset yarn proxy:
    yarn config delete proxy
    yarn config delete https-proxy

According to a Stack Overflow guide, many development workflows benefit from transparent proxy routing[reference:42].

Outcome: npm and yarn package downloads work through the proxy.

10. Proxy Persistence and Automation

For a long-term WSL2 proxy configuration, you need to make proxy settings persistent across sessions. According to a guide from Imsxx, you can automate this with a script that auto-detects the gateway IP[reference:43].

Method 1: Add to your shell profile (~/.bashrc or ~/.zshrc)
Step 1: Open your shell profile:
    nano ~/.bashrc

Step 2: Add this auto-detect script for NAT mode:
    export host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
    export http_proxy="http://$host_ip:7890"
    export https_proxy="http://$host_ip:7890"
    export all_proxy="socks5://$host_ip:7890"

Step 3: For Mirrored mode:
    export http_proxy="http://127.0.0.1:7890"
    export https_proxy="http://127.0.0.1:7890"

Step 4: Save and reload:
    source ~/.bashrc[reference:44]

Method 2: WSL Settings app (Windows 11)
Step 1: Open the Start menu and type "WSL Settings"[reference:45]
Step 2: Go to the Networking tab
Step 3: Enable "Mirrored networking mode"
Step 4: Enable "Auto proxy"[reference:46]

According to a Microsoft Q&A guide, mirrored mode is the most reliable long-term solution[reference:47].

This WSL2 proxy configuration approach ensures your proxy settings survive terminal restarts and WSL2 reboots.

Outcome: Proxy settings are automatically applied every time you open WSL2.

11. Frequently Asked Questions

Why does WSL2 need separate proxy configuration?

WSL2 uses a virtualized network adapter with NAT, which means it has its own IP address space and does not automatically inherit Windows proxy settings. According to Microsoft’s WSL troubleshooting, WSL2 runs behind a host-based NAT, creating a virtualized network interface that insulates the Linux instance from the Windows host[reference:48].

What is the easiest way to configure WSL2 proxy?

Enable Mirrored Networking mode on Windows 11 22H2 or later. Create %USERPROFILE%\.wslconfig with networkingMode=mirrored and [experimental] autoProxy=true, then restart WSL with wsl --shutdown[reference:49].

How do I find the Windows host IP from inside WSL2?

Run cat /etc/resolv.conf | grep nameserver | awk '{print $2}' in WSL2. This returns the gateway IP (e.g., 172.20.0.1)[reference:50].

Why does sudo apt update fail with proxy errors?

sudo clears environment variables by default for security reasons. According to a Debian guide, APT has its own configuration system and you need to configure APT proxy directly in /etc/apt/apt.conf.d/proxy.conf or use sudo -E to preserve environment variables[reference:51][reference:52].

How do I configure Git over SSH through a proxy?

Install connect-proxy with sudo apt install connect-proxy, then configure ~/.ssh/config with ProxyCommand connect -H 127.0.0.1:7890 %h %p[reference:53].

What is the difference between HTTP_PROXY and HTTPS_PROXY?

HTTP_PROXY is for HTTP traffic, while HTTPS_PROXY is for HTTPS traffic. According to a guide, these environment variables affect TCP connections (curl/apt/git) but not UDP (DNS/QUIC)[reference:54].

Why does WSL2 lose connectivity when I connect to a VPN?

VPNs modify the Windows network stack and can interfere with WSL2’s NAT networking. According to a Windows Forum guide, mirrored networking mode greatly improves compatibility with VPNs[reference:55].

Can I use SOCKS5 proxies with WSL2?

Yes. Set all_proxy="socks5://127.0.0.1:7890" or configure individual tools. For SSH, use connect -S instead of connect -H[reference:56].

Does WSL2 autoProxy work on Windows 10?

No. According to a GitHub guide, autoProxy=true and networkingMode=mirrored are Windows 11 22H2+ features. On Windows 10, only basic settings are supported[reference:57].

Where can I find more WSL2 troubleshooting help?

Explore our Windows 11 Troubleshooting Hub and guides on WSL2 DNS resolution fix and Hyper‑V network adapter not working.

12. Conclusion

WSL2 proxy configuration guide covers everything you need to route traffic through a proxy server when using Windows Subsystem for Linux 2. From Mirrored Networking mode and autoProxy to manual NAT configuration, APT proxy, Git proxy, SSH proxy, and persistence, this guide provides all proven methods. According to Microsoft’s WSL troubleshooting documentation, WSL2 uses a virtualized network adapter with its own IP address, which means proxy settings from Windows do not automatically carry over to your Linux environment.

Start with the simplest approach — enabling Mirrored Networking and autoProxy on Windows 11 22H2+ — and use NAT mode with gateway IP or manual configurations only if needed.

For more Windows troubleshooting, explore our Windows 11 Troubleshooting Hub and guides on WSL2 DNS resolution fix and Hyper‑V network adapter not working.

With the right approach from this WSL2 proxy configuration guide, you can restore network connectivity and keep your WSL2 development environment running smoothly.