How to Use cURL with Proxy — Complete Command Reference

cURL is the universal command-line tool for making HTTP requests, and it has excellent built-in proxy support. Whether you are testing API endpoints, debugging proxy configurations, or writing shell scripts for data collection, knowing how to use cURL with proxies is an essential skill.

This reference covers every cURL proxy option with practical examples. You will learn HTTP, HTTPS, and SOCKS5 proxy configuration, authentication methods, environment variables, and advanced techniques for scripting and automation.

Basic Proxy Syntax

The simplest way to route a cURL request through a proxy is the -x (or --proxy) flag:

`bash curl -x http://gate.resproxy.io:7777 https://httpbin.org/ip `

This sends the request to httpbin.org through the proxy at gate.resproxy.io:7777. The response shows the proxy's IP address, not yours.

You can also use the long form:

`bash curl --proxy http://gate.resproxy.io:7777 https://httpbin.org/ip `

Both forms are identical. The -x shorthand is more common in scripts.

Proxy Authentication

Most proxy providers require authentication. Include credentials directly in the proxy URL or use the -U flag:

`bash # Method 1: Credentials in the URL curl -x http://username:password@gate.resproxy.io:7777 https://httpbin.org/ip

# Method 2: Separate -U flag (preferred — avoids special character issues) curl -x http://gate.resproxy.io:7777 -U username:password https://httpbin.org/ip

# Method 3: Prompt for password interactively curl -x http://gate.resproxy.io:7777 -U username https://httpbin.org/ip `

Method 2 (-U flag) is recommended because it handles special characters in passwords correctly. If your password contains @, :, or %, embedding it in the URL can cause parsing errors.

HTTPS Proxy (CONNECT Tunnel)

When you access an HTTPS URL through an HTTP proxy, cURL automatically uses the CONNECT method to establish a tunnel. The proxy sees the destination hostname but cannot read the encrypted content:

`bash curl -x http://gate.resproxy.io:7777 -U user:pass https://secure-site.com/api/data `

For an HTTPS proxy (where the connection to the proxy itself is encrypted), use the --proxy-insecure flag if the proxy uses a self-signed certificate:

`bash curl -x https://gate.resproxy.io:7778 --proxy-insecure https://httpbin.org/ip `

SOCKS5 Proxy

cURL supports SOCKS4, SOCKS4a, SOCKS5, and SOCKS5-hostname protocols:

`bash # SOCKS5 with local DNS resolution curl --socks5 gate.resproxy.io:1080 https://httpbin.org/ip

# SOCKS5 with remote DNS resolution (recommended — prevents DNS leaks) curl --socks5-hostname gate.resproxy.io:1080 https://httpbin.org/ip

# SOCKS5 with authentication curl --socks5-hostname gate.resproxy.io:1080 -U user:pass https://httpbin.org/ip

# Using -x with socks5:// scheme curl -x socks5h://user:pass@gate.resproxy.io:1080 https://httpbin.org/ip `

The socks5h:// scheme is equivalent to --socks5-hostname — the "h" means the proxy handles DNS resolution, which is more secure and prevents DNS leaks.

Environment Variables

You can set proxy configuration globally using environment variables so that all cURL commands (and many other tools) use the proxy automatically:

`bash # Set proxy for HTTP requests export http_proxy="http://user:pass@gate.resproxy.io:7777"

# Set proxy for HTTPS requests export https_proxy="http://user:pass@gate.resproxy.io:7777"

# Bypass proxy for specific domains export no_proxy="localhost,127.0.0.1,.internal.company.com"

# Now all curl requests use the proxy automatically curl https://httpbin.org/ip `

To disable the environment variable proxy for a single request:

`bash curl --noproxy "*" https://httpbin.org/ip `

.curlrc Configuration File

For persistent proxy settings, create a ~/.curlrc file:

`bash # ~/.curlrc proxy = http://gate.resproxy.io:7777 proxy-user = username:password `

Every cURL command will now use these settings. Override them per-command with --noproxy "*" or a different -x value.

Scripting with cURL and Proxies

Here are practical script examples for common tasks:

Checking Your Proxy IP

`bash curl -s -x http://user:pass@gate.resproxy.io:7777 https://httpbin.org/ip | jq .origin `

Testing Proxy Response Time

`bash curl -x http://user:pass@gate.resproxy.io:7777 \ -o /dev/null -s -w "Connect: %{time_connect}s\nTotal: %{time_total}s\n" \ https://httpbin.org/ip `

Rotating Through Multiple Requests

`bash #!/bin/bash PROXY="http://user:pass@gate.resproxy.io:7777" URLS=("https://example.com/page1" "https://example.com/page2" "https://example.com/page3")

for url in "${URLS[@]}"; do echo "Fetching: $url" response=$(curl -s -x "$PROXY" -w "\n%{http_code}" "$url") http_code=$(echo "$response" | tail -1) body=$(echo "$response" | head -n -1) echo "Status: $http_code | Size: ${#body} bytes" sleep 1 done `

Downloading Files Through a Proxy

`bash curl -x http://user:pass@gate.resproxy.io:7777 \ -L -o output.html \ --retry 3 --retry-delay 2 \ https://example.com/large-page `

The -L flag follows redirects, --retry handles transient failures, and --retry-delay adds a pause between retries.

Useful cURL Proxy Flags Reference

Debugging Proxy Connections

When things go wrong, use verbose output to diagnose:

`bash # Verbose output shows the full proxy handshake curl -v -x http://user:pass@gate.resproxy.io:7777 https://httpbin.org/ip

# Even more detail with --trace curl --trace proxy-debug.txt -x http://user:pass@gate.resproxy.io:7777 https://httpbin.org/ip `

Look for these common issues in verbose output:

• 407 Proxy Authentication Required — Check your username and password
• Connection refused — The proxy host or port is wrong
• SSL certificate problem — Add --proxy-insecure or configure the CA bundle
• Timeout — Increase timeout with --connect-timeout 30 --max-time 60

Best Practices

1. Use -U for credentials instead of embedding them in the URL to handle special characters correctly
2. Set no_proxy for internal hosts to avoid routing local traffic through the proxy
3. Use socks5h:// (with hostname resolution) to prevent DNS leaks
4. Add retry logic in scripts with --retry 3 --retry-delay 2
5. Test with httpbin.org/ip to verify your proxy is working before hitting target sites
6. Use rotating proxies for multiple requests to avoid IP-based blocking

Getting Started

Sign up and configure your proxy credentials through the getting started guide. For the full cURL manual including all proxy-related options, see the official cURL documentation.

cURL's proxy support makes it the perfect tool for testing and debugging your proxy setup before integrating into larger applications.