How to fix Error response from daemon: Get https://registry-1.docker.io/v2/: Proxy Authentication Required in Docker

The Docker daemon does not read your shell environment. On systemd-based Linux, give it a drop-in override:

# Create the override directory
sudo mkdir -p /etc/systemd/system/docker.service.d

# Create the proxy configuration file
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null << 'EOF'
[Service]
Environment="HTTP_PROXY=http://username:password@proxy.example.com:8080"
Environment="HTTPS_PROXY=http://username:password@proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.example.com"
EOF

Replace username, password, proxy.example.com, and 8080 with your real values.

Secure the file — it contains credentials in plaintext:

sudo chmod 600 /etc/systemd/system/docker.service.d/http-proxy.conf
sudo chown root:root /etc/systemd/system/docker.service.d/http-proxy.conf

Reload systemd and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify the variables were applied:

sudo systemctl show --property=Environment docker

If possible, prefer a dedicated proxy service account over your personal credentials, since the secret is stored on disk.

Docker Engine 23.0 and later support a proxies block in the daemon configuration file, which is often cleaner than a systemd drop-in:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "proxies": {
    "http-proxy": "http://username:password@proxy.example.com:8080",
    "https-proxy": "http://username:password@proxy.example.com:8080",
    "no-proxy": "localhost,127.0.0.1,.example.com"
  }
}
EOF

Restrict permissions, since the password is stored in cleartext:

sudo chmod 600 /etc/docker/daemon.json
sudo chown root:root /etc/docker/daemon.json

Restart Docker to apply:

sudo systemctl restart docker

Avoid defining the proxy in both `daemon.json` and a systemd drop-in at the same time — pick one source of truth to prevent confusing precedence conflicts. If you switch to daemon.json, remove the systemd http-proxy.conf file.

If the proxy password contains characters that are significant inside a URL, encode them or the daemon will parse the proxy URL incorrectly. Common encodings:

| Character | URL Encoded |
|-----------|-------------|
| @ | %40 |
| # | %23 |
| $ | %24 |
| % | %25 |
| & | %26 |
| ! | %21 |
| ? | %3F |
| = | %3D |
| : | %3A |
| space | %20 |

Example: the password P@ss#word! becomes P%40ss%23word%21:

Environment="HTTPS_PROXY=http://username:P%40ss%23word%21@proxy.example.com:8080"

Note that you must URL-encode the value even when using EnvironmentFile= or daemon.json, because the proxy URL is parsed as a URL in every case. If you use an environment file, secure it the same way:

sudo tee /etc/docker/proxy.env > /dev/null << 'EOF'
HTTP_PROXY=http://username:P%40ss%23word%21@proxy.example.com:8080
HTTPS_PROXY=http://username:P%40ss%23word%21@proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1,.example.com
EOF
sudo chmod 600 /etc/docker/proxy.env
sudo chown root:root /etc/docker/proxy.env

sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null << 'EOF'
[Service]
EnvironmentFile=/etc/docker/proxy.env
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Docker's Go-based runtime chooses the proxy variable based on the request's URL scheme. Registry traffic to https://registry-1.docker.io/v2/ is selected by HTTPS_PROXY, so if only HTTP_PROXY is set, HTTPS registry requests are sent directly (or unproxied) and fail. Always set both:

Environment="HTTP_PROXY=http://username:password@proxy.example.com:8080"
Environment="HTTPS_PROXY=http://username:password@proxy.example.com:8080"

The proxy URL itself normally uses the http:// scheme even for HTTPS_PROXY: the client opens an HTTP CONNECT tunnel to the proxy and the end-to-end TLS to the registry is then tunneled through it. Use an https:// proxy scheme only if your proxy explicitly terminates TLS on its listener.

Confirm both variables are present on the daemon:

sudo systemctl show --property=Environment docker | tr ' ' '\n' | grep -i proxy

On Docker Desktop the daemon runs inside a managed VM, so configure the proxy through the app rather than editing host systemd files:

1. Open Docker Desktop and click the gear icon (Settings).
2. Go to Resources > Proxies.
3. Enable Manual proxy configuration.
4. Enter the proxy URLs (including credentials if required):
- Web Server (HTTP): http://username:password@proxy.example.com:8080
- Secure Web Server (HTTPS): http://username:password@proxy.example.com:8080
- Bypass: localhost,127.0.0.1
5. Click Apply & Restart.

Note: the proxies block in ~/.docker/config.json configures proxies that are injected into containers at build/run time, not the daemon's own registry connection. For the daemon's proxy on Docker Desktop, use the Settings UI above.

If the corporate proxy requires NTLM, NTLMv2, or Kerberos/Negotiate authentication (common with Microsoft proxies), Docker cannot authenticate directly. Run a local proxy bridge such as Cntlm that handles the NTLM handshake and exposes an unauthenticated local endpoint:

# Install Cntlm
sudo apt-get install cntlm   # Debian/Ubuntu
sudo dnf install cntlm       # RHEL/Fedora

Generate a password hash so the cleartext password does not have to live in the config:

cntlm -H -u username -d DOMAIN

Put the generated PassNTLMv2 hash into /etc/cntlm.conf (do not store the plaintext Password line in production):

Username    your_username
Domain      YOUR_DOMAIN
PassNTLMv2  <hash-from-cntlm-H>

Proxy       corporate-proxy.example.com:8080
NoProxy     localhost, 127.0.0.*, 10.*, .example.com

Listen      127.0.0.1:3128

Secure and start it:

sudo chmod 600 /etc/cntlm.conf
sudo systemctl enable --now cntlm

Then point the Docker daemon at the local, credential-free bridge (no secrets in the Docker config):

Environment="HTTP_PROXY=http://127.0.0.1:3128"
Environment="HTTPS_PROXY=http://127.0.0.1:3128"

Confirm the daemon picked up the proxy and can reach a registry:

# Docker reports its configured proxies near the bottom of the output
docker info

# Pull a small image end to end
docker pull hello-world

If it still fails, raise the daemon log level via daemon.json (do not run a second dockerd by hand while the service is running):

{
  "debug": true
}

Then restart and follow the logs:

sudo systemctl restart docker
sudo journalctl -u docker.service -f

You can also reproduce the request outside Docker to isolate the proxy from the daemon:

https_proxy='http://username:password@proxy.example.com:8080' \
  curl -sv https://registry-1.docker.io/v2/

A 200 or 401 Unauthorized (registry auth, not 407) from this curl confirms the proxy itself is accepting your credentials.

If docker login itself reports proxy/auth problems after the proxy is correctly configured, refresh the stored registry credentials. Prefer docker logout over deleting your config file, because ~/.docker/config.json also holds your proxy and credential-store settings:

# Remove cached Docker Hub auth token only
docker logout

# Log back in once the proxy is working
docker login

If you suspect a corrupt credential helper, inspect (do not blindly delete) the config:

grep -E 'credsStore|credHelpers' ~/.docker/config.json

Only if the file is genuinely corrupt, back it up before removing it so you can restore your proxy block:

cp ~/.docker/config.json ~/.docker/config.json.bak