How to Use a Proxy with Docker Containers

Docker is widely used for containerized application deployment, development, and testing. In many environments — corporate networks, cloud instances behind firewalls, or proxy-dependent workflows — configuring Docker to work through a proxy server is essential. Docker requires proxy configuration at multiple levels: the Docker daemon, the Docker CLI, image builds, and running containers.

This guide covers every proxy configuration point in the Docker ecosystem, with practical examples for HTTP, HTTPS, and SOCKS5 proxies.

Understanding Docker’s Proxy Architecture

Docker has three distinct contexts where proxy settings are needed:

Docker daemon — The background service that manages containers. Needs a proxy to pull images from registries (Docker Hub, GHCR, etc.).
Docker CLI / build context — Used during docker build for downloading packages inside Dockerfiles.
Running containers — Applications inside containers that need to reach external services through a proxy.

Each context requires separate configuration because they operate in isolated network environments.

Method 1: Configure Proxy for the Docker Daemon

The Docker daemon needs a proxy to pull images from container registries when your network requires proxy access.

Step 1: Create the Daemon Proxy Configuration

Create the Docker daemon override directory:

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

Step 2: Create the Proxy Configuration File

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

Add the following content:

[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,.local,docker-registry.example.com"

Step 3: Reload and Restart Docker

sudo systemctl daemon-reload
sudo systemctl restart docker

Step 4: Verify the Configuration

sudo systemctl show --property=Environment docker

This should display the proxy environment variables.

Test by Pulling an Image

docker pull nginx

If the pull succeeds, the daemon proxy is working.

Method 2: Configure Proxy for Docker CLI and Builds

Docker 17.07+ supports a config.json file that automatically injects proxy settings into builds and containers.

Step 1: Edit Docker Config

nano ~/.docker/config.json

Add or merge the proxy configuration:

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

How This Works

When this configuration is set:

docker build commands automatically have HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables injected into the build context.
docker run commands automatically have these variables set inside the container.
The proxy variables are not baked into the final image layers (Docker strips them from the build history).

Multiple Proxy Configurations

You can define different proxy settings for different Docker contexts:

{
    "proxies": {
        "default": {
            "httpProxy": "http://proxy.example.com:8080",
            "httpsProxy": "http://proxy.example.com:8080"
        },
        "tcp://docker-host-2:2376": {
            "httpProxy": "http://other-proxy.example.com:8080"
        }
    }
}

Method 3: Configure Proxy in Dockerfile

For fine-grained control during image builds, set proxy variables directly in the Dockerfile.

Using ARG for Build-Time Proxy

FROM ubuntu:22.04

# Accept proxy settings as build arguments
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# These are automatically used by apt, pip, curl, etc.
RUN apt-get update && apt-get install -y \
    curl \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install requests flask

Build with proxy arguments:

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 myapp .

Using ENV for Runtime Proxy

If the application inside the container also needs the proxy:

FROM python:3.11

# Build-time proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Runtime proxy
ENV http_proxy=${HTTP_PROXY}
ENV https_proxy=${HTTPS_PROXY}

COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt

CMD ["python", "app.py"]

Important: ARG values are not persisted in the final image. ENV values are. Use ARG for build-time proxy and ENV only if the running container needs the proxy.

Method 4: Configure Proxy in Docker Compose

Docker Compose allows you to set proxy environment variables in the docker-compose.yml file.

Per-Service Proxy Configuration

version: '3.8'

services:
  web:
    build: .
    environment:
      - HTTP_PROXY=http://proxy.example.com:8080
      - HTTPS_PROXY=http://proxy.example.com:8080
      - NO_PROXY=localhost,127.0.0.1,db
    depends_on:
      - db

  scraper:
    build: ./scraper
    environment:
      - HTTP_PROXY=http://scraping-proxy.example.com:8080
      - HTTPS_PROXY=http://scraping-proxy.example.com:8080
    depends_on:
      - db

  db:
    image: postgres:15
    # Database does not need a proxy

Using .env File

Create a .env file in the same directory as docker-compose.yml:

HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

Reference in docker-compose.yml:

services:
  web:
    build:
      context: .
      args:
        - HTTP_PROXY=${HTTP_PROXY}
        - HTTPS_PROXY=${HTTPS_PROXY}
    environment:
      - HTTP_PROXY
      - HTTPS_PROXY
      - NO_PROXY

Build Arguments in Compose

services:
  app:
    build:
      context: .
      args:
        HTTP_PROXY: http://proxy.example.com:8080
        HTTPS_PROXY: http://proxy.example.com:8080

Method 5: Configure Proxy for Running Containers

Via docker run

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 \
           myapp

Via docker exec

If a container is already running:

docker exec -e HTTP_PROXY=http://proxy.example.com:8080 mycontainer curl https://api.ipify.org

Method 6: Using SOCKS5 Proxies with Docker

Docker’s built-in proxy support is limited to HTTP/HTTPS. For SOCKS5 proxies, you need a workaround.

Option A: Use a SOCKS-to-HTTP Proxy Converter

Run a container that converts SOCKS5 to HTTP:

docker run -d --name socks-to-http \
    -p 8118:8118 \
    -e SOCKS_PROXY=socks5://proxy.example.com:1080 \
    wernight/privoxy

Then configure Docker to use http://localhost:8118 as its HTTP proxy.

Option B: Use redsocks Inside a Container

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y redsocks iptables

COPY redsocks.conf /etc/redsocks.conf
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

Option C: Network-Level SOCKS5

Configure SOCKS5 at the host network level and let Docker use the host network:

docker run --network host \
    -e ALL_PROXY=socks5://proxy.example.com:1080 \
    myapp

Proxy Configuration for Docker Desktop

Docker Desktop on Windows

Open Docker Desktop.
Click the gear icon (Settings).
Go to Resources > Proxies.
Toggle Manual proxy configuration to On.
Enter:

HTTP Proxy: http://proxy.example.com:8080
HTTPS Proxy: http://proxy.example.com:8080
Bypass: localhost,127.0.0.1,.local

Click Apply & Restart.

Docker Desktop on macOS

Open Docker Desktop.
Click Settings (gear icon).
Go to Resources > Proxies.
Configure the proxy settings.
Click Apply & Restart.

Practical Use Cases

Web Scraping Containers

Running web scrapers in Docker containers with rotating proxies:

services:
  scraper-us:
    build: ./scraper
    environment:
      - HTTP_PROXY=http://us-proxy.example.com:8080

  scraper-uk:
    build: ./scraper
    environment:
      - HTTP_PROXY=http://uk-proxy.example.com:8080

  scraper-de:
    build: ./scraper
    environment:
      - HTTP_PROXY=http://de-proxy.example.com:8080

Each container scrapes through a different geographic proxy, using mobile proxies for the most authentic residential IPs.

CI/CD Pipeline Proxy

# GitLab CI example
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"
  NO_PROXY: "docker,registry.local"

build:
  script:
    - docker build --build-arg HTTP_PROXY=$HTTP_PROXY -t myapp .
    - docker push myapp

Troubleshooting Docker Proxy Issues

Cannot Pull Images

Verify daemon proxy configuration: sudo systemctl show --property=Environment docker
Check proxy accessibility: curl -x http://proxy:8080 https://registry-1.docker.io/v2/
Ensure NO_PROXY does not accidentally match the registry hostname.
Restart Docker after configuration changes.

Build Fails at Package Installation

Ensure build args are passed: --build-arg HTTP_PROXY=...
Check that ~/.docker/config.json proxy settings are correct.
Verify the proxy allows access to package repositories (pypi.org, npmjs.com, etc.).

Container Cannot Reach External Services

Check that runtime environment variables are set: docker exec container env | grep -i proxy
Verify the proxy is accessible from inside the container network.
If using Docker’s bridge network, ensure the proxy is reachable from the container’s network namespace.

Proxy Credentials Exposed in Image Layers

Use ARG instead of ENV for build-time proxy settings — ARG values are not persisted.
Use ~/.docker/config.json proxy configuration, which Docker automatically strips from build history.
Never hardcode proxy credentials in Dockerfiles committed to version control.

For definitions of proxy terms referenced in this guide, see our proxy glossary.

Conclusion

Docker proxy configuration operates at three levels: the daemon (for pulling images), the build context (for installing packages during builds), and running containers (for application-level proxy needs). The ~/.docker/config.json approach is the most elegant for development, while docker-compose.yml environment variables provide the best flexibility for multi-service deployments. Always use ARG over ENV for build-time proxy settings to avoid leaking credentials into image layers.