Docker Proxy Configuration 2026: Pull Images Behind Corporate Proxy

Updated May 2026 with Docker daemon, CLI, build, registry mirror, and corporate proxy checks.

Docker needs internet access to pull images and communicate with registries. In corporate environments, network traffic often flows through proxy servers. Without proper proxy configuration, Docker fails with pull timeouts, proxy authentication errors, or blocked registry access.

Quick Reference

Use these commands first when Docker cannot pull images behind a corporate proxy:

# Docker daemon proxy for image pulls
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.corp.local,registry.internal"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker
docker pull hello-world

# Docker CLI and build proxy defaults
mkdir -p ~/.docker
cat > ~/.docker/config.json <<'EOF'
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:8080",
      "httpsProxy": "http://proxy.example.com:8080",
      "noProxy": "localhost,127.0.0.1,.corp.local,registry.internal"
    }
  }
}
EOF

If Git fails in the same network, pair this setup with the Git proxy configuration guide.

What is Docker Proxy Configuration?

Docker proxy configuration tells the Docker daemon and containers how to route network traffic through proxy servers. This involves configuring environment variables and systemd service files to ensure Docker can communicate with external registries and services.

Key Scenarios

• Docker daemon proxy: Enables Docker to pull images from Docker Hub, private registries, and pull-through mirrors
• Container runtime proxy: Allows containers to access external resources during build and runtime
• Build-time proxy: Passes proxy settings to containers during image build
• Docker CLI proxy: Configures Docker client and build defaults through ~/.docker/config.json
• Corporate registry proxy: Keeps private registries, Supabase internal registries, and mirror endpoints out of proxy routing with NO_PROXY

Configure Docker Daemon Proxy

Create a systemd drop-in directory for Docker service:

sudo mkdir -p /etc/systemd/system/docker.service.d

Create a proxy configuration file:

sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Add proxy settings:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,*.local"

Reload systemd and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify configuration:

sudo systemctl show --property=Environment docker

Configure Container Build Proxy

Set proxy for Docker build using --build-arg:

docker build --build-arg HTTP_PROXY=http://proxy.example.com:8080 \
             --build-arg HTTPS_PROXY=http://proxy.example.com:8080 \
             --build-arg NO_PROXY=localhost,127.0.0.1 \
             -t myimage .

Or create ~/.docker/config.json for persistent build settings:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:8080",
      "httpsProxy": "http://proxy.example.com:8080",
      "noProxy": "localhost,127.0.0.1,*.local"
    }
  }
}

Configure Container Runtime Proxy

Pass environment variables when running containers:

docker run -e HTTP_PROXY=http://proxy.example.com:8080 \
           -e HTTPS_PROXY=http://proxy.example.com:8080 \
           -e NO_PROXY=localhost,127.0.0.1 \
           myimage

For Docker Compose, add to docker-compose.yml:

services:
  myservice:
    environment:
      - HTTP_PROXY=http://proxy.example.com:8080
      - HTTPS_PROXY=http://proxy.example.com:8080
      - NO_PROXY=localhost,127.0.0.1

Operational Tips

• NO_PROXY variable: Always include localhost, 127.0.0.1, internal registries, Kubernetes service ranges, and corporate DNS suffixes to prevent routing local traffic through the proxy
• Authentication: Use format http://username:[email protected]:8080 for authenticated proxies
• Testing: Verify configuration with docker pull hello-world after setup
• Troubleshooting: Check Docker logs with journalctl -u docker.service if pull operations fail, then test the proxy directly with curl -I -x http://proxy.example.com:8080 https://registry-1.docker.io/v2/
• Security: Store sensitive proxy credentials in Docker secrets or external credential managers

Conclusion

Proper proxy configuration ensures Docker works seamlessly in corporate networks. By configuring daemon, build, and runtime proxy settings, you maintain full Docker functionality while complying with network policies. For intelligent incident management and automated issue resolution, consider using Akmatori, an open-source AI agent platform that helps SRE teams respond to infrastructure incidents faster.

Related network and proxy guides: Git proxy configuration, check Linux Ethernet speed, and Cloudflare R2 with s3cmd.

FAQ

• Why does Docker ignore system proxy settings?

  • Docker daemon runs as a system service and doesn't inherit user environment variables. Configure proxy in systemd service files.

• How to configure proxy for specific Docker registries?

  • Use registry-specific configuration in /etc/docker/daemon.json with registry-mirrors and insecure-registries options.

• Can I use different proxies for HTTP and HTTPS?

  • Yes, set separate HTTP_PROXY and HTTPS_PROXY environment variables with different proxy endpoints.