How to configure and use proxy servers in cURL?

Proxy configuration is an important feature of cURL in enterprise environments and network debugging. Properly configuring proxies enables bypassing network restrictions, protecting privacy, and analyzing traffic.

Basic Proxy Configuration

bash
# HTTP proxy
curl -x http://proxy.example.com:8080 https://api.example.com
curl --proxy http://proxy.example.com:8080 https://api.example.com

# HTTPS proxy
curl -x https://proxy.example.com:443 https://api.example.com

# SOCKS proxy
curl -x socks5://proxy.example.com:1080 https://api.example.com
curl -x socks5h://proxy.example.com:1080 https://api.example.com

Proxy Authentication

bash
# Username and password authentication
curl -x http://user:password@proxy.example.com:8080 https://api.example.com

# Using -U parameter
curl -x http://proxy.example.com:8080 -U user:password https://api.example.com

# NTLM authentication
curl -x http://proxy.example.com:8080 \
     --proxy-ntlm \
     -U user:password \
     https://api.example.com

# Digest authentication
curl -x http://proxy.example.com:8080 \
     --proxy-digest \
     -U user:password \
     https://api.example.com

Proxy Types Comparison

Proxy Type	Protocol	Features	Use Case
HTTP	http://	Plain text	Simple proxy, caching
HTTPS	https://	Encrypted	Secure proxy
SOCKS4	socks4://	TCP forwarding	Basic proxy
SOCKS5	socks5://	UDP support, auth	Advanced proxy
SOCKS5H	socks5h://	Remote DNS resolution	Privacy protection

Environment Variables

bash
# Set environment variables
export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export no_proxy="localhost,127.0.0.1,.example.com"

# Use environment variables
curl https://api.example.com

# Ignore environment variables
curl --noproxy "*" https://api.example.com

Proxy Bypass

bash
# Bypass specific domains
curl --noproxy "localhost,127.0.0.1,internal.example.com" \
     -x http://proxy.example.com:8080 \
     https://api.example.com

# Bypass all proxies
curl --noproxy "*" https://api.example.com

Proxy Debugging

bash
# View proxy connection process
curl -v -x http://proxy.example.com:8080 https://api.example.com 2>&1 | grep -i proxy

# Test proxy connectivity
curl -v -x http://proxy.example.com:8080 http://www.google.com

# Check real IP through proxy
curl -x http://proxy.example.com:8080 https://api.ipify.org

Advanced Proxy Configuration

bash
# Proxy auto-configuration (PAC)
curl --proxy-header "User-Agent: MyApp/1.0" \
     -x http://proxy.example.com:8080 \
     https://api.example.com

# Proxy tunneling (for HTTPS)
curl -x http://proxy.example.com:8080 \
     --proxy-tunnel \
     https://api.example.com

# Specify proxy TLS version
curl -x https://proxy.example.com:443 \
     --proxy-tlsv1.2 \
     https://api.example.com

# Proxy certificate verification
curl -x https://proxy.example.com:443 \
     --proxy-cacert /path/to/proxy-ca.crt \
     https://api.example.com

# Ignore proxy certificate verification
curl -x https://proxy.example.com:443 \
     --proxy-insecure \
     https://api.example.com

Practical Scenarios

bash
# Scenario 1: Corporate network access to internet
curl -x http://corporate-proxy.company.com:8080 \
     -U "domain\\username:password" \
     https://api.github.com/user

# Scenario 2: Use SSH tunnel as proxy
# First create tunnel: ssh -D 1080 user@remote-server
curl -x socks5://localhost:1080 https://api.example.com

# Scenario 3: Load testing through proxy
for i in {1..10}; do
    curl -x http://proxy.example.com:8080 \
         -w "Request $i: %{http_code}\n" \
         -o /dev/null -s \
         https://api.example.com &
done
wait

# Scenario 4: Packet capture analysis
# Use with Charles/Fiddler
curl -x http://localhost:8888 \
     -k \
     https://api.example.com

Proxy Configuration File

bash
# ~/.curlrc configuration file
proxy = "http://proxy.example.com:8080"
proxy-user = "username:password"
noproxy = "localhost,127.0.0.1"

# Use configuration file
curl https://api.example.com

# Ignore configuration file
curl -q https://api.example.com

Common Issues

bash
# Issue 1: Proxy connection timeout
# Solution: Increase timeout
curl -x http://proxy.example.com:8080 \
     --connect-timeout 30 \
     https://api.example.com

# Issue 2: Proxy authentication failed
# Solution: Check authentication method and credentials
curl -v -x http://proxy.example.com:8080 \
     --proxy-ntlm -U "domain\\user:pass" \
     https://api.example.com

# Issue 3: HTTPS through HTTP proxy fails
# Solution: Use CONNECT method (default) or tunnel
curl -x http://proxy.example.com:8080 \
     --proxy-tunnel \
     https://api.example.com

# Issue 4: DNS leak
# Solution: Use socks5h for remote DNS resolution
curl -x socks5h://proxy.example.com:1080 \
     https://api.example.com

# Issue 5: Proxy server certificate issue
# Solution: Specify CA or ignore verification
curl -x https://proxy.example.com:443 \
     --proxy-insecure \
     https://api.example.com

Complete Proxy Example

bash
# Enterprise proxy configuration
curl -x http://corporate-proxy.company.com:8080 \
     --proxy-ntlm \
     -U "COMPANY\\username:password" \
     --proxy-header "User-Agent: CorporateApp/1.0" \
     --noproxy "localhost,127.0.0.1,*.internal.company.com" \
     --connect-timeout 30 \
     --max-time 60 \
     -H "Authorization: Bearer api_token" \
     https://api.external-service.com/data

​