wslc pull fails behind a proxy or in restricted regions
wslc pull talks to the container registry directly over HTTPS. If you are behind
a corporate proxy, a PAC script, or in a region where Docker Hub is restricted, pulls can time
out with errors like:
Get "https://registry-1.docker.io/v2/": context deadline exceeded
Error code: E_FAILAutoConfigURL) or a proxy where
http_proxy is populated but HTTPS_PROXY is left empty.
- wslc pull then bypasses the proxy for HTTPS registry traffic and times out.
**Status as of wslc 2.9.4.0:** there is no documented wslc proxy setting. The
issues request one (and a fix to wslc settings pointing at a dead
aka.ms/wslc-settings link, #40979).
**What you can try today:**
1. Set both proxy variables in the invoking shell so HTTPS has a route:
```powershell
$env:HTTPS_PROXY = "http://proxy.corp:8080"
$env:HTTP_PROXY = "http://proxy.corp:8080"
$env:NO_PROXY = "localhost,127.0.0.1"
wslc pull alpine
```
2. If the proxy only supports PAC, export the resolved PAC URL to HTTPS_PROXY
manually.
3. For Zscaler/PAC specifically, check that HTTPS_PROXY is being set — the issue
reports it is left empty, which is the root cause.
## Restricted regions (China): no registry mirror yet
Docker Hub is slow or blocked in some regions. Docker solves this with
registry-mirrors in daemon.json. wslc has no equivalent
setting as of 2.9.4.0 — tracked in
microsoft/WSL #40951.
**Workaround:** reference the mirror host directly in the image name. The issue documents this
working pattern:
```powershell
wslc pull docker.m.daocloud.io/library/alpine:latest
```
The image is pulled from the mirror; the container runs identically. You just prefix the mirror
host instead of relying on a global rewrite.
## Other registry gaps to know about
- Credential helpers (short-lived OAuth tokens for e.g. Google Cloud Artifact
Registry) are not supported — only wslc login basic auth. Requested in
#41030.
- Push to a different registry/repository is not supported; wslc assumes the
docker.io namespace. Requested in
#41040.
- Non-Docker-style registries (e.g. Zot, which do not return 200 on a bare
/v2/ probe) fail authentication. Requested in
#41067.
## Where to track progress
All of these are public issues in the microsoft/WSL repository under the wslc
label. Bookmark the proxy issues (#40945, #40981) and the mirror request (#40951) — when
Microsoft lands a settings.yaml proxy/mirror option, those issues close and this
page updates.
For images that fail to pull for other reasons, check the
image compatibility matrix or paste the error into the
error diagnostic.