How to Use cURL With a Proxy: HTTP, HTTPS and SOCKS5 Examples

TL;DR:

• Use -x or --proxy to route a cURL request through an HTTP, HTTPS, or SOCKS proxy. Keep the target URL separate from the proxy address.
• An HTTPS target does not require an HTTPS proxy. An HTTP proxy commonly creates a CONNECT tunnel to an HTTPS destination; an https:// proxy URL additionally encrypts the client-to-proxy hop.
• Use socks5h:// when the proxy should resolve the target hostname. Plain socks5:// resolves it locally, which can expose DNS behavior or fail on a proxy-only hostname.
• Keep credentials out of URLs and source files. Quote shell variables, protect config files, and never publish real usernames, passwords, or gateway tokens.
• Verify more than the exit IP. Check status, expected content, location, DNS behavior, and a non-proxy control request on an authorized target.

cURL proxy support is built into the command most developers already use for HTTP diagnostics. A single option can route a request through an HTTP gateway, an HTTPS proxy, or a SOCKS5 server, with authentication and host-exclusion rules when required.

The syntax is simple. The network behavior is not. HTTPS targets use tunnels, SOCKS schemes decide where DNS resolution happens, environment variables differ by case, and credentials can leak through careless command history.

This guide starts with a minimal command and builds a configuration that works on macOS, Linux, and Windows.

Quick cURL Proxy Example

Use an authorized public test target and a proxy you control or are permitted to use:

curl --proxy "http://proxy.example.com:8080" \
  --connect-timeout 10 \
  --max-time 30 \
  --show-error \
  "https://example.com/"

The long option --proxy and short option -x are equivalent. The cURL command-line reference documents supported proxy schemes, authentication options, and exclusion behavior.

Add --verbose during diagnosis to see the connection sequence. Remove verbose output from normal logs because headers and connection details may be sensitive.

How cURL Proxy URLs Work

The proxy option accepts a scheme, host, and port:

scheme://proxy-host:port

Common schemes are:

• http:// for an HTTP proxy;
• https:// for TLS between cURL and the proxy;
• socks4:// and socks4a:// for SOCKS4 variants;
• socks5:// for SOCKS5 with local target-name resolution;
• socks5h:// for SOCKS5 with proxy-side target-name resolution.

The target URL remains the final argument. Do not combine the target and proxy into one URL.

Use an HTTP Proxy With cURL

For a plain HTTP target, cURL sends the request through the proxy. For an HTTPS target, it normally asks the proxy to open a tunnel with the HTTP CONNECT method and then performs TLS with the destination through that tunnel.

# HTTP target through an HTTP proxy
curl -x "http://proxy.example.com:8080" "http://example.com/"

# HTTPS target through the same HTTP proxy
curl -x "http://proxy.example.com:8080" "https://example.com/"

The second command still protects the HTTP request and response with destination TLS. The client-to-proxy connection itself is not separately encrypted before the tunnel is established, so local network observers can see the proxy connection and tunnel destination metadata.

The HTTP Semantics specification defines the CONNECT method used to establish a tunnel.

Use an HTTPS Proxy With cURL

An HTTPS proxy encrypts the hop from cURL to the proxy. Prefix the proxy URL with https://:

curl --proxy "https://proxy.example.com:8443" \
  --proxy-cacert "/path/to/proxy-ca.pem" \
  "https://example.com/"

--proxy-cacert supplies a CA bundle for verifying the proxy's certificate when the default trust store does not contain the issuing CA. Do not use --proxy-insecure as a permanent fix; it disables proxy certificate verification.

Not every proxy endpoint accepts TLS. Match the URL scheme and port to the provider's documentation.

Use a SOCKS5 Proxy With cURL

SOCKS proxies operate below HTTP and can carry several application protocols. For web requests, the important choice is where the target hostname is resolved.

# Resolve example.com on the local machine
curl --proxy "socks5://proxy.example.com:1080" "https://example.com/"

# Send example.com to the proxy for resolution
curl --proxy "socks5h://proxy.example.com:1080" "https://example.com/"

# Equivalent long option for proxy-side hostname resolution
curl --socks5-hostname "proxy.example.com:1080" "https://example.com/"

Use socks5h:// when the target hostname should not be resolved by the local resolver, when the hostname is only visible from the proxy network, or when local DNS gives the wrong regional result.

The Everything cURL SOCKS guide explains the local-versus-proxy name-resolution distinction. The protocol itself is defined in RFC 1928.

Authenticate to a Proxy Safely

Use --proxy-user or -U instead of embedding credentials in the proxy URL:

export PROXY_HOST="proxy.example.com"
export PROXY_PORT="8080"
export PROXY_USER="replace-with-user"
read -r -s -p "Proxy password: " PROXY_PASS
printf '\n'

curl --proxy "http://${PROXY_HOST}:${PROXY_PORT}" \
  --proxy-user "${PROXY_USER}:${PROXY_PASS}" \
  "https://example.com/"

unset PROXY_PASS

Quoting prevents spaces, dollar signs, exclamation marks, and other shell characters from being reinterpreted. Do not type a real password directly into a shared shell command, ticket, screenshot, or repository.

Command-line arguments may be visible to local process inspection. For automation, prefer a secret manager that injects a short-lived value into an isolated job. If you use a cURL config file, restrict its permissions and keep it outside version control:

proxy = "http://proxy.example.com:8080"
proxy-user = "replace-with-user:replace-with-password"
connect-timeout = 10
max-time = 30
show-error

On macOS or Linux, set permissions with chmod 600 proxy.conf, then run curl --config proxy.conf https://example.com/. Delete or rotate the credential if the file is exposed.

Set Proxy Environment Variables

cURL recognizes environment variables for applications that should share proxy routing:

export http_proxy="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export ALL_PROXY="socks5h://proxy.example.com:1080"
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

curl "https://example.com/"

The lowercase http_proxy form is intentional. cURL accepts only lowercase for that variable as a security precaution, while other proxy variables may be uppercase. ALL_PROXY acts as a fallback; protocol-specific variables take precedence.

The Everything cURL environment-variable guide documents case rules and NO_PROXY matching.

Use environment variables for controlled jobs, not as a global desktop setting you forget is active. Inspect them when a request unexpectedly uses a proxy.

Exclude Selected Hosts From Proxy Routing

Use --noproxy for one command:

curl --proxy "http://proxy.example.com:8080" \
  --noproxy "localhost,127.0.0.1,.internal.example.com" \
  "https://internal.example.com/health"

An exact hostname matches that host. A domain beginning with a dot matches the domain and its subdomains. An asterisk disables proxying for all hosts, which is useful only for diagnosis.

Treat exclusion lists as policy. A broad suffix can route sensitive or internal destinations outside the intended gateway.

Configure cURL Proxy on Windows

The cURL options themselves are cross-platform. Only environment and quoting syntax change.

In PowerShell:

$env:http_proxy = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.internal.example.com"

curl.exe --proxy "http://proxy.example.com:8080" `
  --proxy-user "replace-with-user:replace-with-password" `
  --show-error `
  "https://example.com/"

Remove-Item Env:http_proxy, Env:HTTPS_PROXY, Env:NO_PROXY

Use curl.exe in Windows PowerShell environments where curl may resolve to another command. In Command Prompt, variables use %NAME%; for repeatable automation, prefer PowerShell or a protected cURL config file.

Verify the Proxy Exit IP

First record a direct control response, then make the same request through the proxy:

curl --silent --show-error "https://httpbin.org/ip"

curl --silent --show-error \
  --proxy "http://proxy.example.com:8080" \
  "https://httpbin.org/ip"

Different IP values show that routing changed. They do not prove the requested country, session behavior, anonymity level, or target-page success.

For a real acceptance test, check all of the following:

• cURL exits successfully;
• the HTTP status is expected;
• the body contains a required marker;
• the exit IP or region meets the task policy;
• DNS resolution happens on the intended side;
• no unapproved host appears in verbose connection output.

You can print status and the remote peer address without saving the body:

curl --output /dev/null --silent --show-error \
  --write-out 'status=%{http_code} peer=%{remote_ip}\n' \
  --proxy "http://proxy.example.com:8080" \
  "https://example.com/"

Common cURL Proxy Errors

407 Proxy Authentication Required

The proxy did not accept the supplied credentials or the account/channel cannot serve the request. Confirm the username format, password, channel state, and allowed authentication method. Keep target-site 401 errors separate from proxy 407 errors.

Connection timed out

Check the proxy hostname, port, firewall, VPN conflicts, and whether the endpoint expects HTTP, HTTPS, or SOCKS. Use --connect-timeout to bound connection setup and --max-time to bound the whole operation.

Proxy certificate error

For an HTTPS proxy, make sure the proxy hostname matches its certificate and the correct CA is trusted. A destination CA option and a proxy CA option protect different TLS connections.

Could not resolve host

If the message names the target while using socks5://, switch to socks5h:// when proxy-side DNS is intended. If it names the proxy, fix local DNS or the proxy hostname.

Direct request works but proxy request fails

Compare verbose output, target policy, proxy location, protocol, and body marker. An exit IP endpoint may work while the actual target rejects the traffic, so always test the permitted production hostname separately.

Use cURL With Scrapeless Proxies

The Scrapeless Proxy Solutions product page covers residential, datacenter, static ISP, and IPv6 options. Create a channel in the Scrapeless dashboard, then copy the generated gateway, username, and password. Do not invent the username format; it can include proxy type, location, and session parameters selected for that channel.

Set the generated values as protected variables:

export SCRAPELESS_PROXY_HOST="gw-us.scrapeless.io"
export SCRAPELESS_PROXY_PORT="8789"
export SCRAPELESS_PROXY_USER="replace-with-generated-username"
read -r -s -p "Scrapeless proxy password: " SCRAPELESS_PROXY_PASS
printf '\n'

curl --proxy "http://${SCRAPELESS_PROXY_HOST}:${SCRAPELESS_PROXY_PORT}" \
  --proxy-user "${SCRAPELESS_PROXY_USER}:${SCRAPELESS_PROXY_PASS}" \
  --connect-timeout 10 \
  --max-time 30 \
  --show-error \
  "https://httpbin.org/ip"

unset SCRAPELESS_PROXY_PASS

The gateway above is a current documented US endpoint; choose the endpoint closest to your application from the dashboard or current documentation. Exit geography is controlled separately through the generated username parameters.

Follow the Scrapeless proxy setup guide to create a channel, then use the proxy feature reference for current gateway and location fields.

If you are choosing between address types, the datacenter vs. residential proxy guide explains the operating tradeoffs. Review Scrapeless pricing for current terms.

cURL Proxy Checklist

• Confirm the target and proxy are authorized for the task.
• Match the proxy URL scheme to the provider endpoint.
• Use socks5h:// when proxy-side DNS is required.
• Keep credentials outside URLs, prompts, logs, and repositories.
• Quote every variable that may contain special characters.
• Bound connection and total time.
• Set NO_PROXY or --noproxy narrowly.
• Compare a direct control with the proxied response.
• Validate expected content, not only exit IP.
• Remove verbose diagnostics from normal logs.

Create a Scrapeless proxy channel and test it first against one public endpoint you are allowed to access.

FAQ

Q: What is the cURL proxy syntax?

Use curl --proxy "scheme://host:port" "https://target.example.com/". The short form is curl -x "scheme://host:port" "https://target.example.com/".

Q: How do I add a proxy username and password?

Use --proxy-user "username:password" and keep credentials out of the proxy URL. In automation, inject the values from a protected secret store.

Q: What is the difference between socks5:// and socks5h://?

With socks5://, cURL resolves the target hostname locally. With socks5h://, the SOCKS5 proxy resolves it.

Q: Can I use an HTTP proxy for an HTTPS website?

Yes. cURL commonly uses HTTP CONNECT to create a tunnel through the HTTP proxy, then performs TLS with the HTTPS destination.

Q: How do I disable a proxy for one host?

Use --noproxy "host.example" for one command or add the host to NO_PROXY. Keep the list narrow and review domain-suffix matches.