New videos every week — proxies, VPNs & antidetect browsers, explained.

Subscribe
GuidesNov 2, 202612 min read

How to Use Proxies with cURL: HTTP, HTTPS and SOCKS5 Examples

Copy-paste cURL proxy commands for HTTP, HTTPS and SOCKS5: -x, auth, env vars, socks5h DNS, .curlrc and fixes for 407 and timeout errors.

Table of contents

cURL is the fastest way to find out whether a proxy actually works. One command tells you if the proxy accepts your credentials, which IP the target site sees, how long the connection takes and where it breaks when it fails. This guide gives you copy-paste cURL commands for HTTP, HTTPS and SOCKS5 proxies, explains the flags that matter, and walks through the errors you are most likely to hit, from 407 Proxy Authentication Required to silent DNS leaks.

Every command below was checked against the official curl documentation (the curl man page and the Everything curl book maintained by the curl project). Replace proxy.example.com, the port and the credentials with the values from your provider's dashboard.

Quick answer

The core pattern is curl -x http://USER:PASS@HOST:PORT https://target.com. Swap http:// for socks5h:// to use a SOCKS5 proxy that also resolves DNS for you, or for https:// if your provider offers a TLS-encrypted proxy endpoint.

How cURL talks to a proxy

When you pass a proxy to cURL, it no longer connects to the website directly. It opens a connection to the proxy and asks the proxy to fetch the page on its behalf. What happens next depends on the proxy type and on whether the target URL is HTTP or HTTPS.

  • HTTP proxy, plain HTTP target: cURL sends the full request (including the full URL) to the proxy, and the proxy forwards it. The proxy can read and even modify the traffic.
  • HTTP proxy, HTTPS target: cURL sends a CONNECT request asking the proxy to open a tunnel to the target on port 443. After that, TLS runs end to end between cURL and the website, so the proxy only sees the hostname and the amount of data, not the content.
  • SOCKS proxy: the proxy relays raw TCP connections. It does not understand HTTP at all, which is why SOCKS works for almost any protocol.
  • HTTPS proxy: the connection between cURL and the proxy itself is encrypted with TLS, so nobody on your local network can read your proxy credentials or the CONNECT request.

If the HTTP versus SOCKS distinction is new to you, our explainer on SOCKS5 vs HTTP proxies covers it in depth. For cURL, the practical difference comes down to which scheme you put in front of the proxy address.

Flow diagram showing cURL sending a request to a proxy, the proxy forwarding it to a target website, and the response returning, with labels CURL, PROXY, TARGET SITE, CONNECT TUNNEL and RESPONSE
An HTTPS request through an HTTP proxy: cURL asks the proxy to open a CONNECT tunnel, then TLS runs straight through to the target.

The basic command: -x and --proxy

The -x flag (long form --proxy) is all you need for most jobs. The format is [protocol://]host[:port].

curl -x http://proxy.example.com:8080 https://httpbin.org/ip
curl --proxy http://proxy.example.com:8080 https://httpbin.org/ip

Both lines do the same thing. A few defaults are worth remembering because they explain a lot of confusing failures:

  • If you leave off the scheme, cURL assumes an HTTP proxy.
  • If you leave off the port, cURL assumes port 1080, for historical reasons. Most commercial proxies use a different port (often 8080, 3128, 7777 or a provider-specific gateway port), so always include it.
  • For an https:// proxy with no port, the default is 443.
  • A -x value on the command line overrides any proxy set in environment variables.

The endpoint https://httpbin.org/ip simply echoes back the IP address it sees, which makes it a handy first test. If the response shows your proxy's exit IP instead of your own, the proxy is working. You can use any similar IP-echo service; the point is to compare the result with and without -x.

Adding proxy authentication

Paid proxies almost always require a username and password (or an IP allowlist). cURL gives you two ways to pass credentials.

Option 1: credentials inside the proxy URL

curl -x http://USERNAME:PASSWORD@proxy.example.com:8080 https://httpbin.org/ip

Option 2: the -U / --proxy-user flag

curl -U USERNAME:PASSWORD -x proxy.example.com:8080 https://httpbin.org/ip
curl --proxy-user USERNAME:PASSWORD -x proxy.example.com:8080 https://httpbin.org/ip

Keep -U (proxy credentials) separate in your head from -u (credentials for the target website). Mixing them up is one of the most common reasons for a 407 error.

Special characters in passwords

cURL URL-decodes the username and password in a proxy string. That means characters such as @, :, # or % in your password will break parsing unless you percent-encode them. Use %40 for @ and %3A for a colon:

# password is p@ss:word
curl -x "http://user:p%40ss%3Aword@proxy.example.com:8080" https://httpbin.org/ip

Many providers put targeting parameters (country, city, session ID) inside the username, separated by dashes or underscores. Those work fine as long as you quote the whole proxy string so your shell does not interpret any characters. Check your provider's documentation for the exact username syntax, since it differs between networks.

Non-Basic authentication schemes

By default cURL uses Basic authentication with the proxy. Some corporate proxies expect something else, and the Proxy-Authenticate header in the 407 response tells you which. cURL supports --proxy-digest, --proxy-ntlm and --proxy-negotiate, or you can let it pick with --proxy-anyauth (at the cost of an extra round trip).

curl -U user:pass -x proxy.example.com:8080 --proxy-anyauth https://example.com

Keep passwords out of your shell history

Anything you type after -U lands in your shell history and can show up in the process list. For shared machines, put credentials in a config file with tight permissions (see the .curlrc section below) or in an environment variable loaded from a protected file.

Using SOCKS5 proxies with cURL

cURL supports SOCKS4, SOCKS4a, SOCKS5 and SOCKS5-hostname. You choose the version with the scheme in the -x value or with a dedicated flag.

# SOCKS5, DNS resolved locally by curl
curl -x socks5://user:pass@proxy.example.com:1080 https://httpbin.org/ip
curl --socks5 proxy.example.com:1080 https://httpbin.org/ip

# SOCKS5-hostname, DNS resolved by the proxy
curl -x socks5h://user:pass@proxy.example.com:1080 https://httpbin.org/ip
curl --socks5-hostname proxy.example.com:1080 https://httpbin.org/ip

socks5 vs socks5h: the DNS detail that matters

The single letter h changes who looks up the target's hostname:

SchemeWho resolves the hostnameIPv6 supportWhen to use it
socks4://cURL (your machine)NoLegacy proxies only
socks4a://The proxyNoLegacy proxies that need remote DNS
socks5://cURL (your machine)YesWhen you deliberately want local DNS
socks5h://The proxyYesDefault choice for privacy and geo-targeting

With plain socks5://, your machine asks your own DNS resolver for the target's IP address. That lookup goes to your ISP or local resolver, which can reveal which sites you visit, and it can also return a server in your own region rather than the proxy's region, which matters for geo-specific content. With socks5h://, the hostname travels to the proxy and the proxy resolves it from its own location.

Split comparison diagram: on the left socks5 with DNS lookup done on the local machine, marked with an amber warning; on the right socks5h with DNS lookup done at the proxy, marked with a teal shield; labels SOCKS5, SOCKS5H, LOCAL DNS, PROXY DNS
With socks5 your own machine looks up the hostname; with socks5h the proxy does it, so the lookup does not leak to your local resolver.

If you are not sure which one your workflow needs, use socks5h://. The only common reason to choose socks5:// is when the target hostname only exists in your local network or hosts file.

HTTPS proxies and TLS options

An "HTTPS proxy" is not the same as using an HTTP proxy to reach HTTPS sites. It means the hop between cURL and the proxy is itself encrypted. Without it, HTTP and SOCKS proxy traffic between you and the proxy is sent in clear text, including Basic auth credentials. Only use the https:// scheme if your provider actually exposes a TLS endpoint; pointing it at a plain HTTP port will fail during the handshake.

curl -x https://user:pass@proxy.example.com:443 https://httpbin.org/ip

Useful related flags:

  • --proxy-cacert FILE trusts a custom CA certificate for the proxy, which is common with corporate or self-hosted proxies.
  • --proxy-insecure skips verification of the proxy's certificate. Use it only for short local tests, never in production scripts.
  • --proxy-http2 asks cURL to try HTTP/2 when talking to an HTTPS proxy. By default it uses HTTP/1.1.

Setting proxies with environment variables

If you run many commands through the same proxy, environment variables save typing. cURL reads them automatically before each run.

export http_proxy="http://user:pass@proxy.example.com:8080"
export https_proxy="http://user:pass@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

curl https://httpbin.org/ip

A few rules from the curl documentation catch people out:

  • http_proxy only works in lowercase. cURL deliberately ignores HTTP_PROXY because CGI scripts receive an HTTP_PROXY variable from any incoming request that carries a Proxy: header, which historically caused security problems. Other variables, such as HTTPS_PROXY, work in either case.
  • The variable is named after the target scheme, not the proxy type. https_proxy is used for HTTPS URLs, even if the proxy itself is a plain HTTP proxy.
  • ALL_PROXY covers every protocol, but a protocol-specific variable takes precedence when both exist.
  • NO_PROXY takes a comma-separated list. A leading dot matches a whole domain, a single * disables proxying, and since cURL 7.86.0 you can use CIDR ranges such as 192.168.0.0/16.

To ignore an environment proxy for a single command, use --noproxy "*" or pass an empty proxy with -x "".

Saving proxy settings in .curlrc

For a persistent setup that does not leak into other tools, put the proxy in a cURL config file. cURL reads a default config automatically, checking $CURL_HOME/.curlrc, then $XDG_CONFIG_HOME/curlrc, then $HOME/.curlrc on Linux and macOS.

# ~/.curlrc
proxy = "http://proxy.example.com:8080"
proxy-user = "user:pass"
noproxy = "localhost,127.0.0.1"
connect-timeout = 15

Lock the file down with chmod 600 ~/.curlrc. You can also keep separate profiles and load one explicitly with -K (--config), for example curl -K ~/proxies/us.conf https://example.com. Run curl -q when you need to bypass the default file for a single command; -q must be the first argument.

Tip for rotating proxies

Keep one small config file per proxy location or session type. Switching between them with -K is far less error-prone than editing long command lines.

Verifying and timing a proxy with cURL

Once the proxy responds, cURL can show you exactly what happened. These are the checks we run first:

# 1. Which IP does the target see?
curl -s -x http://user:pass@proxy.example.com:8080 https://httpbin.org/ip

# 2. Full handshake details (proxy connect, CONNECT response, TLS)
curl -v -x http://user:pass@proxy.example.com:8080 https://example.com -o /dev/null

# 3. Timing breakdown
curl -s -o /dev/null -x http://user:pass@proxy.example.com:8080 \
  -w "connect: %{time_connect}s  tls: %{time_appconnect}s  total: %{time_total}s  code: %{http_code}\n" \
  https://example.com

The verbose output (-v) shows whether cURL connected to the proxy, what the proxy answered to CONNECT, and whether the TLS handshake with the target succeeded. The -w format string prints timing variables so you can compare proxies or locations side by side. For a fuller testing routine covering anonymity and leak checks, see our guide on how to test a proxy.

Sending headers only to the proxy

Some providers accept options through custom headers. A normal -H header goes to the target site; --proxy-header goes only to the proxy, including on the CONNECT request:

curl --proxy-header "X-Example-Option: value" -x proxy.example.com:8080 https://example.com

Troubleshooting common cURL proxy errors

When a proxy command fails, read the cURL exit code and the first lines of -v output together. Here is what the usual suspects mean:

SymptomLikely causeWhat to try
Exit code 5, "Could not resolve proxy"Typo in the proxy hostname, or DNS cannot resolve the gatewayCheck the hostname against your dashboard; try the gateway IP if the provider lists one
Exit code 7, "Failed to connect"Wrong port, proxy down, or a firewall blocking outbound traffic to that portConfirm the port; test from another network; check whether your IP must be allowlisted
407 Proxy Authentication RequiredMissing or wrong credentials, unencoded special characters, or using -u instead of -UPercent-encode the password, use -U, try --proxy-anyauth
Exit code 28, "Operation timed out"Slow or overloaded exit node, or a blocked routeAdd --connect-timeout 15 --max-time 60, rotate to a new session, try another location
Exit code 97, "Proxy handshake error"SOCKS handshake failed, often a wrong scheme or SOCKS credentialsMake sure the port really is SOCKS, check the scheme (socks5h:// vs http://)
Target returns 403 or a CAPTCHAThe proxy works, but the site distrusts the IP or your request patternTry a residential or mobile IP, slow down, send realistic headers
IP check shows your real IPAn environment variable or .curlrc is overriding, or NO_PROXY matches the hostRun with -v and -q, unset proxy variables, check NO_PROXY

Don't "fix" errors with -k

-k (--insecure) disables certificate checks for the target site and --proxy-insecure does the same for the proxy. Neither fixes a proxy problem, and leaving them in scripts lets anyone in the middle read or alter your traffic.

Practical recipes

Rotate through a list of proxies

while read -r p; do
  printf '%s -> ' "$p"
  curl -s --max-time 20 -x "$p" https://httpbin.org/ip || echo "failed"
done < proxies.txt

Each line in proxies.txt holds one full proxy URL, such as http://user:pass@host:port or socks5h://user:pass@host:port.

Download a file through a proxy and retry on failure

curl -x socks5h://user:pass@proxy.example.com:1080 \
  --retry 3 --retry-delay 5 --connect-timeout 15 \
  -L -o report.pdf https://example.com/report.pdf

Use different proxies for different requests in one command

The --next (-:) flag resets options between URLs, so each URL can get its own proxy:

curl -x http://us.proxy.example.com:8080 https://httpbin.org/ip \
  --next -x http://de.proxy.example.com:8080 https://httpbin.org/ip

When to move beyond cURL

cURL is ideal for testing a proxy, debugging an integration and running small scripted jobs. It is less comfortable when you need to parse responses, manage cookies across many requests, handle retries with backoff, or run thousands of requests concurrently. At that point, most teams move the same proxy settings into a programming language. If Python is your tool of choice, our guide to using proxies with Python Requests shows how the same HTTP and SOCKS5 URLs translate directly into code.

Keep cURL around even then. When a scraper starts failing, reproducing a single request with curl -v -x ... is usually the quickest way to tell whether the problem is the proxy, the credentials or the target site.

Responsible use

A proxy changes where your requests come from; it does not change what you are allowed to do. Respect each site's terms and robots rules, keep request rates reasonable, and avoid collecting personal data you have no legal basis to process. Choose proxy providers that are transparent about how they source their IPs, especially for residential and mobile networks.

Final thoughts

Most proxy setups in cURL come down to one flag: -x with the right scheme. Use http:// for standard HTTP proxies, socks5h:// for SOCKS5 with remote DNS, and https:// only when your provider offers an encrypted proxy endpoint. Pass credentials with -U or inside the URL with special characters encoded, remember that http_proxy is lowercase-only, and lean on -v and -w whenever something looks wrong. With those habits, cURL becomes the quickest way to test any proxy before you trust it with real work.

Frequently asked questions

Pass the proxy with the -x or --proxy flag, for example curl -x http://host:port https://example.com. Add credentials inside the URL as user:pass@host:port or with the -U flag. If you omit the scheme, cURL treats the proxy as an HTTP proxy.

If you don't specify a port, cURL assumes port 1080 for HTTP and SOCKS proxies, and 443 for https:// proxies. Most commercial proxy gateways use a different port, so always include the port from your provider's dashboard.

With socks5://, cURL resolves the target hostname on your own machine and sends the IP to the proxy. With socks5h://, the hostname is sent to the proxy and resolved there. socks5h avoids leaking DNS lookups to your local resolver and gives geo-accurate results, so it is usually the better default.

Either embed them in the proxy URL, such as http://user:pass@host:port, or use -U user:pass (also written --proxy-user). Percent-encode special characters in the password, for example %40 for @ and %3A for a colon, because cURL URL-decodes proxy credentials.

cURL only accepts the lowercase http_proxy variable. The uppercase HTTP_PROXY is ignored on purpose because CGI environments create it from an incoming Proxy request header, which has caused security issues. Other variables such as HTTPS_PROXY and ALL_PROXY work in either case.

Check that the username and password match your provider's dashboard, percent-encode any special characters, and make sure you used -U for the proxy rather than -u, which is for the target site. If the proxy needs a scheme other than Basic, try --proxy-anyauth or the specific --proxy-digest or --proxy-ntlm flag.

Request an IP-echo endpoint such as https://httpbin.org/ip with and without -x and compare the addresses. Add -v to see cURL connect to the proxy and the proxy's reply to the CONNECT request. If your real IP still appears, check for a .curlrc file, environment variables or a NO_PROXY entry that matches the host.

Yes. Set proxy and proxy-user lines in your default config file, usually ~/.curlrc, or export http_proxy and https_proxy in your shell profile. Use --noproxy "*" or curl -q to skip the proxy for a single command when you need a direct connection.

Found this useful? Share it.