{"id":1075,"date":"2026-10-12T17:37:40","date_gmt":"2026-10-12T14:37:40","guid":{"rendered":"https:\/\/mexela.com\/blog\/wsl2-proxy-setup\/"},"modified":"2026-10-12T20:46:46","modified_gmt":"2026-10-12T17:46:46","slug":"wsl2-proxy-setup","status":"publish","type":"post","link":"https:\/\/mexela.com\/blog\/wsl2-proxy-setup\/","title":{"rendered":"WSL2 Proxy Setup: Windows, Linux and Localhost Troubleshooting"},"content":{"rendered":"<p class=\"mexela-answer\">Configure and verify the proxy inside the WSL Linux process making the request. Windows proxy settings, Linux environment variables, and access to a proxy running on the Windows host are separate layers. Determine the networking mode before assuming that localhost reaches the Windows service.<\/p>\n<p><strong>Reviewed and locally tested: October 12, 2026.<\/strong> Version and route observations below describe the stated test environment. A working local route does not establish a provider&#8217;s public exit, country, anonymity, speed, or uptime.<\/p>\n<h2 id=\"inventory\">Record the distribution and Linux client first<\/h2>\n<pre><code class=\"language-powershell\">wsl --version\nwsl --list --verbose\nwsl -d Ubuntu-24.04 -- curl --version<\/code><\/pre>\n<p>The commands inspect versions and distribution identity; replace the distribution name with your actual target. Our tested environment was WSL 2.7.10.0, Ubuntu 24.04, Linux Python 3.12.3 and curl 8.5.0. A different installed distribution can have another client version and environment. No WSL configuration or global proxy setting was changed for these tests. See <a href=\"https:\/\/learn.microsoft.com\/en-us\/windows\/wsl\/basic-commands\">WSL basic commands<\/a>.<\/p>\n<h2 id=\"environment\">Set a narrow environment for a Linux request<\/h2>\n<pre><code class=\"language-bash\">http_proxy=&quot;$PROXY_URL&quot; https_proxy=&quot;$PROXY_URL&quot; \\\nNO_PROXY=&quot;localhost,127.0.0.1&quot; \\\ncurl --silent --show-error --fail --max-time 8 &quot;$CHECK_URL&quot;<\/code><\/pre>\n<p>Run the command in the intended Linux shell with PROXY_URL and CHECK_URL supplied securely. Use lowercase http_proxy for Linux curl. The example bypasses local destinations deliberately; a local diagnostic will therefore stay direct unless you change that rule for the specific test. Keep previous environment values available for restoration instead of appending permanent exports during initial troubleshooting.<\/p>\n<p>A Windows environment variable is not evidence that a Linux child received an equivalent value. Check the configuration inside the process you are testing, and avoid printing the full environment because proxy URLs can contain credentials. Compare <a href=\"\/blog\/http-proxy-https-proxy-no-proxy\/\">the environment guide<\/a> when Windows and Linux results differ.<\/p>\n<h2 id=\"host-address\">Reach a Windows-host proxy according to the network mode<\/h2>\n<p>In default NAT networking, a service on the Windows host may require the host address visible from Linux. Microsoft&#8217;s <a href=\"https:\/\/learn.microsoft.com\/en-us\/windows\/wsl\/networking\">WSL networking guide<\/a> describes obtaining that address from the Linux default route, while mirrored networking changes localhost interoperability. Mirrored mode and automatic proxy inheritance have Windows and WSL prerequisites; check the current documentation and your configuration before relying on them.<\/p>\n<pre><code class=\"language-bash\">ip route show default<\/code><\/pre>\n<p>Inspect the gateway for the NAT case, confirm where the Windows proxy is listening, and check the relevant firewall rule. A listener bound only to Windows loopback may not be reachable using another interface. Changing it to listen broadly is a separate exposure decision, so keep the binding and access policy narrow. The gateway is a routing address, not a fixed value to copy between computers.<\/p>\n<p>For configuration options, consult <a href=\"https:\/\/learn.microsoft.com\/en-us\/windows\/wsl\/wsl-config\">the .wslconfig reference<\/a>. Do not switch networking modes as the first debugging step: establish whether the existing mode, endpoint binding or environment explains the failed request. We did not modify mirrored mode, autoProxy or Windows firewall settings during the local tests.<\/p>\n<h2 id=\"observed\">Actual Linux curl results within WSL<\/h2>\n<table>\n<thead>\n<tr>\n<th>Configuration<\/th>\n<th>Observed local route<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>No proxy variables<\/td>\n<td>Direct<\/td>\n<\/tr>\n<tr>\n<td>lowercase http_proxy<\/td>\n<td>Authenticated HTTP proxy<\/td>\n<\/tr>\n<tr>\n<td>uppercase HTTP_PROXY alone<\/td>\n<td>Direct<\/td>\n<\/tr>\n<tr>\n<td>Matching NO_PROXY=127.0.0.1<\/td>\n<td>Direct<\/td>\n<\/tr>\n<tr>\n<td>Proxy configured; &#8211;noproxy &#8220;&#8221;<\/td>\n<td>Authenticated HTTP proxy<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Each request reached an owned loopback destination inside Ubuntu 24.04. The fixture correlated the upstream socket to the proxy route and kept proxy credentials away from the destination. It did not exercise a proxy on the Windows host. These results establish Linux client behavior inside WSL, not Windows-to-WSL localhost connectivity, DNS privacy or a real public exit. The <a href=\"https:\/\/everything.curl.dev\/usingcurl\/proxies\/env.html\">curl environment reference<\/a> explains the uppercase HTTP_PROXY exception.<\/p>\n<h2 id=\"diagnostics\">Use a sequence that isolates the failed layer<\/h2>\n<p>First make a direct request from the Linux client to the trusted check endpoint. Then confirm the proxy address is reachable from that distribution. Next make one proxied request with a deliberate bypass rule, and compare the destination observation. Finally run the original application using its actual configuration path. Do not infer the application&#8217;s route from a successful Windows browser or a separate Linux curl call.<\/p>\n<p>A connection refusal can be listener binding or reachability. A timeout may be routing, firewall or a missing response. A 407 indicates proxy authentication. A certificate failure requires the correct approved trust chain inside the relevant Linux client; keeping Windows trust correct does not automatically establish Python trust. Use <a href=\"\/blog\/curl-proxy\/\">curl configuration<\/a>, <a href=\"\/blog\/python-httpx-proxy\/\">HTTPX setup<\/a> or <a href=\"\/blog\/python-aiohttp-proxy\/\">aiohttp setup<\/a> according to the failing process.<\/p>\n<h2 id=\"developer-workflow\">Keep editor and CI scopes explicit<\/h2>\n<p>A VS Code remote extension or terminal in WSL can run on the Linux side, while an editor operation runs on Windows. Check <a href=\"\/blog\/vscode-proxy-setup\/\">VS Code network ownership<\/a> before sharing one setting across both. The <a href=\"\/blog\/github-actions-proxy-api-allowlisting\/\">Actions allowlisting workflow<\/a> also had its shell command validated locally in this distribution, but a local shell result does not establish GitHub cloud networking.<\/p>\n<h2 id=\"faq\">Frequently asked questions<\/h2>\n<div class=\"mexela-faq\">\n<h3>Does localhost always reach a proxy running on Windows?<\/h3>\n<p>No. Its meaning depends on the process and WSL networking mode. Identify NAT or mirrored behavior, then test the actual endpoint from the Linux process.<\/p>\n<h3>Can I fix a Linux TLS error by disabling validation?<\/h3>\n<p>Keep validation enabled and diagnose the issuer, hostname and approved CA chain in that client. The required trust store may differ from the Windows editor or browser.<\/p>\n<\/div>\n<h2 id=\"next-step\">Verify one client before increasing workload<\/h2>\n<p>Return to <a href=\"\/blog\/proxy-setup-developer-guides\/\">Proxy Setup and Developer Guides<\/a> for adjacent clients. Use <a href=\"\/blog\/test-if-your-proxy-is-working\/\">the proxy verification checklist<\/a> to record a direct baseline and the destination&#8217;s observation. When that is repeatable, compare <a href=\"\/proxy-locations\/\">Mexela proxy locations<\/a> against the actual destination and location requirements.<\/p>\n<p><!-- mexela-developer-kit-20261012:start --><\/p>\n<h2 id=\"developer-examples-download\">Download the developer examples<\/h2>\n<p><a href=\"\/blog\/wp-content\/uploads\/2026\/10\/mexela-developer-examples-20261012-v1.zip\">Download the developer examples ZIP<\/a> for the locally tested Python clients, environment checks, CI route-check files and native PHP cURL helper. The n8n workflow is a separate illustrative reference: it was not imported or executed in n8n. Read the included README for runtime versions, setup and the limits of each check.<\/p>\n<p>ZIP SHA-256: <code>3a43f7d1e6cbb9b2917dbcf88aaa8fe1a2733c33326187cb89c9a9119aad3e20<\/code>. Keep real proxy credentials and destination secrets in your approved secret store; they are absent from this archive. Start with one approved destination and compare its observation with a direct baseline.<\/p>\n<p><!-- mexela-developer-kit-20261012:end --><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Verify proxy environment variables inside WSL2, distinguish NAT and mirrored localhost behavior, and diagnose the exact Linux request without changing global networking.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[189],"tags":[],"_links":{"self":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts\/1075"}],"collection":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/comments?post=1075"}],"version-history":[{"count":0,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts\/1075\/revisions"}],"wp:attachment":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/media?parent=1075"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/categories?post=1075"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/tags?post=1075"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}