Resolve Docker pull failures on Ubuntu under WSL2 by verifying proxy environment variables and ensuring the Docker Desktop WSL2 backend is correctly configured. Common errors like proxyconnect DNS lookup stem from misconfigured network settings or missing certificates, which can be fixed by updating .docker/config.json and restarting the engine.
Understanding the ProxyConnect Error
When attempting to pull images usingdocker pull in an Ubuntu environment running within WSL2, you may encounter a connection error that mentions proxyconnect or DNS lookups failing. This specific error indicates that the Docker daemon is trying to route traffic through an HTTP or HTTPS proxy, but it cannot resolve the proxy server's hostname or establish a secure connection. This is particularly common in corporate environments where all external traffic must pass through a designated gateway.
The issue often arises because the Docker daemon runs as a Linux process inside the WSL2 instance, while the proxy configuration might be set at the Windows host level or not propagated correctly into the Linux subsystem. If the proxy requires SSL interception (common in enterprise security setups), the Docker client also needs access to the internal Certificate Authority (CA) certificate to validate the proxy's identity. Without this, the TLS handshake fails, resulting in the DNS lookup or connection refusal error.
Verifying Environment Variables
The first step is to ensure that your shell environment correctly defines the proxy settings. In Ubuntu within WSL2, these are typically stored in/etc/environment or user-specific profile files. Check if http_proxy, https_proxy, and no_proxy are set. You can verify this by running:
env | grep -i proxyhttp://proxy.company.com:8080.
Configuring Docker Daemon Settings
Even if your shell has the correct proxy variables, the Docker daemon itself does not automatically inherit them. You must configure the Docker daemon to use the proxy explicitly. This is done by editing the daemon.json file located at /etc/docker/daemon.json in your WSL2 Ubuntu instance.
Create or modify this file to include the proxy settings for both HTTP and HTTPS. For example:
{
"proxies": {
"http-proxy": "http://user:[email protected]:8080",
"https-proxy": "https://user:[email protected]:8080",
"no-proxy": "localhost,127.0.0.1,.internal.domain"
}
}
After saving the file, restart the Docker service to apply the changes. In WSL2 with Docker Desktop, you can do this by stopping the WSL distribution and then restarting Docker Desktop, or by running sudo systemctl restart docker if you are managing the daemon directly within WSL. Note that Docker Desktop manages its own backend, so sometimes restarting the entire Docker Desktop application from the Windows taskbar icon is more effective than restarting the service inside WSL.
Handling Corporate CA Certificates
If your proxy uses a self-signed certificate or an internal CA, you must add the CA certificate to the trusted store of the Docker daemon. Copy the .crt file to /usr/local/share/ca-certificates/ in your WSL2 Ubuntu instance. Then, run sudo update-ca-certificates to refresh the trust store. Finally, ensure the Docker daemon is restarted so it picks up the new certificates. Failure to do this will result in SSL verification errors during image pulls.
Docker Desktop WSL2 Backend Configuration
Docker Desktop on Windows uses WSL2 as a backend engine. It is crucial to ensure that the integration between Docker Desktop and your Ubuntu WSL2 instance is active. Go to Docker Desktop settings, navigate to Resources > WSL Integration, and verify that your Ubuntu distribution is toggled on. If integration is disabled, Docker commands executed in WSL may not communicate properly with the Docker daemon running on the Windows host.
Additionally, check if there are any firewall rules on the Windows host blocking outbound connections from the WSL2 virtual switch. While less common, firewall interference can mimic proxy errors. You can test connectivity from within WSL2 by pinging the proxy IP or using curl to test the proxy endpoint directly.
For more details on managing resources in this setup, see Managing Memory and Processor Swap in WSL2 with Docker Desktop on Ubuntu. Proper resource allocation ensures that the WSL2 instance can handle network I/O without throttling, which might otherwise contribute to timeout-related issues.
Troubleshooting Network Connectivity
If proxy configuration appears correct but issues persist, diagnose the underlying network path. Use nslookup or dig inside WSL2 to check if the proxy hostname resolves correctly. If DNS resolution fails, check your /etc/resolv.conf file. WSL2 often uses a dynamic DNS resolver provided by the Windows host. If this resolver is unreachable or misconfigured, all domain lookups will fail.
You can also try bypassing the proxy temporarily by setting NO_PROXY=* to see if the issue is strictly related to the proxy configuration or general network reachability. If images pull successfully without the proxy, the problem is isolated to the proxy credentials, URL, or certificate chain.
For scenarios involving complex networking between hosts, reviewing how to ping WSL2 from Windows can help isolate whether the issue is specific to Docker or broader network stack problems. Refer to How to Ping WSL2 Ubuntu from Windows Host for diagnostic steps on basic connectivity.
Cleaning Up and Rebuilding
After applying fixes, it is good practice to clear any cached connection attempts. Run docker system prune to remove unused data, though this primarily affects storage. More importantly, ensure no stale processes are holding onto old network configurations. Restarting Docker Desktop completely flushes the state of the WSL2 backend and re-establishes network interfaces.
If you frequently pull large images and notice disk space issues, consider optimizing your storage usage. See Reclaim Space of Pruned Images in Docker WSL for tips on managing disk usage effectively in this environment.
Frequently Asked Questions
Why does docker pull work on Windows but fail in WSL2?
{
"proxies": {
"http-proxy": "http://user:[email protected]:8080",
"https-proxy": "https://user:[email protected]:8080",
"no-proxy": "localhost,127.0.0.1,.internal.domain"
}
}This usually happens because the Docker daemon inside WSL2 does not inherit the Windows environment variables for proxies. You must configure the proxy settings explicitly in the Docker daemon's daemon.json file within the Linux subsystem, rather than relying on Windows shell settings.
How do I fix SSL errors when using a corporate proxy?
You need to install the corporate Certificate Authority (CA) certificate into the WSL2 Ubuntu trust store. Place the .crt file in /usr/local/share/ca-certificates/ and run sudo update-ca-certificates, then restart the Docker service to apply the changes.
What should I do if DNS lookups fail inside WSL2?
Check the contents of /etc/resolv.conf to ensure it points to a valid DNS server. WSL2 relies on the Windows host for DNS resolution; if the host's DNS is unreachable or blocked, update the resolver configuration or ensure Windows firewall allows outbound DNS traffic from the WSL2 virtual adapter.
Can I use different proxy settings for different users?
Yes, you can configure per-user proxy settings in ~/.docker/config.json or via shell environment variables. However, the Docker daemon itself reads global settings from /etc/docker/daemon.json. For user-specific pulls, ensure the shell environment passed to the daemon is consistent.
Does Docker Desktop automatically sync proxy settings from Windows?
No, Docker Desktop does not automatically sync Windows proxy settings into the WSL2 Linux backend. You must manually configure the proxy in the Docker daemon settings within WSL2 or use a startup script to export the necessary environment variables before starting the Docker service.