Skip to content
Web scraping

How to use curl with a proxy: flags, socks5h and errors

curl -x syntax for HTTP and SOCKS5 proxies, plus 15 proxy failures with the exact error curl 8.7.1 and 8.23.0 printed for each.

On this page 19 sections
  1. The command
  2. Choosing the scheme
  3. socks5 vs socks5h: what the proxy actually received
  4. The exit code changed in curl 8.20.0
  5. Why %{http_code} prints 000 when the proxy says 407
  6. Every proxy failure we could trigger, and what curl printed
  7. Reading the exchange with -v
  8. Passwords with special characters
  9. Environment variables, and which ones curl ignores
  10. Proving the proxy was used
  11. Where the time goes through a proxy
  12. Retries that respect the server
  13. Testing a list of proxies
  14. Checking the exit country
  15. Holding one address across requests
  16. Headers, and what they do not change
  17. Saving bandwidth on metered plans
  18. A checklist when a proxy “does not work”
  19. Proxy checker

To use curl with a proxy, pass the proxy URL with -x (long form --proxy) and the target URL as usual: curl -x http://gw.example.net:8000 -U user:pass https://example.com/. An HTTPS target travels through a CONNECT tunnel, so the proxy sees the hostname and nothing else. For a SOCKS5 proxy, write socks5h:// so the proxy resolves the hostname.

The syntax is the easy part. Below it is a failure table built by triggering 15 proxy faults on purpose, alongside five working controls, with the exact error each one printed in two curl builds: 8.7.1, which macOS ships, and 8.23.0, the current release. They disagree on the exit code for the most common failure of all, a rejected password, and a script that checks for exit code 56 will miss it on any curl from 8.20.0 onward.

Tested with curl 8.7.1 (x86_64-apple-darwin25.0, LibreSSL 3.3.6) and curl 8.23.0 (Homebrew, OpenSSL 4.0.3) on macOS 26.6.2, 21 October 2026. Proxies: Squid 6.13 with Basic authentication on 127.0.0.1:3128, and a 100-line SOCKS5 server we wrote to log what each client sends. Every case ran twice. Both runs printed identical output apart from millisecond counts.

The command

# HTTP proxy, no authentication
curl -x http://gw.example.net:8000 https://example.com/

# Credentials in their own flag: keeps them out of the proxy URL
curl -x http://gw.example.net:8000 -U user:pass https://example.com/

# Credentials inline in the proxy URL
curl -x http://user:pass@gw.example.net:8000 https://example.com/

# No scheme at all: curl assumes http://
curl -x gw.example.net:8000 -U user:pass https://example.com/

-U is short for --proxy-user. Do not confuse it with lowercase -u, which sends credentials to the destination site instead. Both curl builds accepted a proxy given with no scheme and treated it as HTTP.

Choosing the scheme

Scheme in -x What curl does Use it when
http:// Plain HTTP to the proxy. HTTPS targets go through a CONNECT tunnel. The provider gives you a host and port. This is most of them.
https:// TLS to the proxy itself, then CONNECT inside it. The provider says the proxy port speaks TLS. On a plain port it fails with exit 35.
socks5:// SOCKS5. Your machine resolves the hostname and sends an IP address. You need local DNS on purpose.
socks5h:// SOCKS5. The hostname goes to the proxy, which resolves it. Any other SOCKS5 use.

socks5 vs socks5h: what the proxy actually received

Our SOCKS5 server logs the address type of every CONNECT request it receives. These are the two lines it wrote for the same https://example.com/ request, once with each scheme:

curl -x socks5://user:pass@127.0.0.1:1080  https://example.com/
  CONNECT atyp=IPv4 target=104.20.23.154:443

curl -x socks5h://user:pass@127.0.0.1:1080 https://example.com/
  CONNECT atyp=DOMAIN target=example.com:443

With socks5:// curl did the DNS lookup itself and handed the proxy a bare IP. Two things follow. Your local resolver learns every hostname you visit, which is a DNS leak. And a site that answers DNS differently per region gets resolved from your location, not the proxy’s, so you can reach the wrong regional endpoint while the proxy dutifully connects from the right country. With socks5h:// the proxy received the name and resolved it. Both builds behaved the same way.

The exit code changed in curl 8.20.0

Here is the same wrong password, sent through the same Squid, by the two builds:

$ /usr/bin/curl -x http://user:wrong@127.0.0.1:3128 https://example.com/
curl: (56) CONNECT tunnel failed, response 407      # curl 8.7.1

$ curl -x http://user:wrong@127.0.0.1:3128 https://example.com/
curl: (7) CONNECT tunnel failed, response 407       # curl 8.23.0

In every release we checked from 8.7.1 to 8.19.0, any non-2xx answer to CONNECT returned exit code 56, the code curl also uses for a connection that dies mid-transfer. curl pull request #21084, merged on 25 March 2026, changed it to 7, the code for “could not connect”. It shipped in curl 8.20.0 on 29 April 2026. We confirmed the switch in the source: lib/cf-h1-proxy.c returns CURLE_RECV_ERROR after that message in the 8.19.0 tag and CURLE_COULDNT_CONNECT from the 8.20.0 tag on.

On curl 8.20.0 and later, exit code 7 no longer means only “the proxy is unreachable”. It also covers a proxy that answered and refused you: a 407, a 403 from proxy policy, or a 503 because the proxy could not reach the site. Read the proxy’s response code, the number at the end of the message or %{http_connect}, before you blame the network.

Why %{http_code} prints 000 when the proxy says 407

Scripts that check status with -w '%{http_code}' get the wrong answer for an HTTPS target. The 407 arrives as the answer to CONNECT, before any request reaches the site, so the destination status stays at 000. curl keeps the proxy’s answer in a separate variable:

$ curl -sS -o /dev/null -x http://user:wrong@127.0.0.1:3128 \
    -w 'connect=%{http_connect} code=%{http_code} exit=%{exitcode}\n' \
    https://example.com/
curl: (7) CONNECT tunnel failed, response 407
connect=407 code=000 exit=7

A plain-HTTP target behaves differently, and this catches people too. There is no tunnel, so the proxy’s 407 comes back as an ordinary response and curl exits 0:

$ curl -sS -o /dev/null -x http://user:wrong@127.0.0.1:3128 \
    -w 'connect=%{http_connect} code=%{http_code} exit=%{exitcode}\n' \
    http://example.com/
connect=000 code=407 exit=0

$ curl -f -sS -o /dev/null -x http://user:wrong@127.0.0.1:3128 http://example.com/
curl: (22) The requested URL returned error: 407

Add -f (--fail) to any script that has to notice a refused request. Without it, an HTTP 407 is a success as far as the exit code is concerned.

Every proxy failure we could trigger, and what curl printed

Each row was produced on purpose against the local test proxies. Where the two builds printed the same thing, the curl 8.23.0 column says so.

Fault curl 8.7.1 curl 8.23.0 What it tells you
Wrong proxy password, HTTPS target (56) CONNECT tunnel failed, response 407 (7) CONNECT tunnel failed, response 407 Credentials. The site was never contacted.
No credentials at all, HTTPS target (56) CONNECT tunnel failed, response 407 (7) CONNECT tunnel failed, response 407 Same message as a wrong password, so check that -U is really set.
Wrong proxy password, HTTP target exit 0, http_code 407 Same Silent unless you pass -f.
Nothing listening on the proxy port (7) Failed to connect to 127.0.0.1 port 3999 after 0 ms: Couldn't connect to server (7) Failed to connect to example.com:443 over proxy 127.0.0.1 after 0 ms: Could not connect to server Wrong port, proxy down, or a firewall. The new wording names both ends.
Proxy hostname does not resolve (5) Could not resolve proxy: proxy.invalid Same Typo in the gateway name, or your DNS.
https:// scheme on a plain HTTP proxy port (35) LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version (35) TLS connect error: error:0A00010B:SSL routines::wrong version number You asked for TLS to the proxy and it does not speak TLS. Use http://.
socks5h:// pointed at an HTTP proxy port (28) Connection timed out after 8006 milliseconds (28) Connection timed out after 8001 milliseconds Protocol mismatch. Squid waited for an HTTP request line that never came, so this looks like a slow proxy. It is not.
http:// pointed at a SOCKS5 port (56) Proxy CONNECT aborted Same Protocol mismatch the other way. Our SOCKS server logged a first byte of 0x43, the “C” of CONNECT.
Wrong SOCKS5 password (97) User was rejected by the SOCKS5 server (1 1). Same SOCKS credentials. Exit 97 is SOCKS-specific.
Proxy accepts TCP and never answers (--connect-timeout 3) (28) Proxy CONNECT aborted due to timeout (28) Connection timed out after 3001 milliseconds Overloaded or wedged proxy. Only a timeout flag stops the wait.
Proxy policy refuses the target port (CONNECT to :8443) (56) CONNECT tunnel failed, response 403 (7) CONNECT tunnel failed, response 403 The 403 came from the proxy, not the site. Squid’s default configuration only allows CONNECT to port 443.
Target hostname does not exist (56) CONNECT tunnel failed, response 503 (7) CONNECT tunnel failed, response 503 The proxy could not resolve the site. Squid sends 503 with X-Squid-Error: ERR_DNS_FAIL.
Target refuses the connection (56) CONNECT tunnel failed, response 503 (7) CONNECT tunnel failed, response 503 Same code as a DNS failure. Only the proxy’s error page tells them apart.
@ and : unencoded in the password (5) Unsupported proxy syntax in 'http://user2:p@ss:word@127.0.0.1:3128': Port number was not a decimal number between 0 and 65535 Same curl split the URL at the wrong @. Percent-encode, or use -U.

Two patterns are worth remembering. A 503 inside “CONNECT tunnel failed” is the proxy reporting that it could not reach the site, which is a different problem from the site refusing you. And the two protocol-mismatch cases fail in completely different ways: one hangs until the timeout, the other aborts at once. If a proxy “times out” on every request, check the scheme before you open a ticket.

Reading the exchange with -v

Verbose output shows the CONNECT request and the proxy’s full answer. This is curl 8.23.0 with a wrong password, trimmed to the proxy part:

* Establishing HTTP proxy tunnel to example.com:443
> CONNECT example.com:443 HTTP/1.1
> Host: example.com:443
> Proxy-Authorization: Basic dXNlcjp3cm9uZw==
> User-Agent: curl/8.23.0
> Proxy-Connection: Keep-Alive
< HTTP/1.1 407 Proxy Authentication Required
< Server: squid/6.13
< X-Squid-Error: ERR_CACHE_ACCESS_DENIED 0
< Proxy-Authenticate: Basic realm="proxy-test"
* Basic authentication problem, ignoring.
< Via: 1.1 proxy-test (squid/6.13)
* CONNECT tunnel failed, response 407
curl: (7) CONNECT tunnel failed, response 407

And the start of a working one, with the right password:

> CONNECT example.com:443 HTTP/1.1
> Proxy-Authorization: Basic dXNlcjpwYXNz
< HTTP/1.1 200 Connection established
* CONNECT tunnel established, response 200
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
...
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 / X25519MLKEM768 / id-ecPublicKey

The order is the diagnosis. The CONNECT line proves curl is using the proxy. “200 Connection established” proves the proxy accepted you. Only after that does the TLS handshake start, end to end with the site, inside the tunnel.

The Proxy-Authorization line is your username and password in base64, which is an encoding, not encryption: dXNlcjpwYXNz decodes to user:pass. Redact it before pasting -v output into a ticket or a chat. With an http:// proxy it also crosses the network in clear text on every request.

Passwords with special characters

A password containing @ or : breaks the inline form, as the table shows. Two fixes worked on both builds:

# Percent-encode the password: @ is %40, : is %3A
curl -x 'http://user2:p%40ss%3Aword@gw.example.net:8000' https://example.com/

# Or keep it out of the URL entirely
curl -x http://gw.example.net:8000 -U 'user2:p@ss:word' https://example.com/

-U splits on the first colon only, so a colon inside the password survives. Single quotes stop the shell from touching the rest.

Environment variables, and which ones curl ignores

curl reads proxy settings from the environment, which is why a request can go through a proxy you never typed. We pointed each variable at a dead port and watched whether curl tried to use it. Both builds gave the same results:

Set in the environment Request Result
https_proxy=http://127.0.0.1:3999 https://example.com/ Used: exit 7
HTTPS_PROXY=http://127.0.0.1:3999 https://example.com/ Used: exit 7
http_proxy=http://127.0.0.1:3999 http://example.com/ Used: exit 7
HTTP_PROXY=http://127.0.0.1:3999 http://example.com/ Ignored: 200, direct
ALL_PROXY=http://127.0.0.1:3999 https://example.com/ Used: exit 7
https_proxy as above, plus -x to a working proxy https://example.com/ -x wins: 200 through the working proxy
https_proxy as above, plus --noproxy '*' https://example.com/ Bypassed: 200, direct
https_proxy as above, plus NO_PROXY=example.com https://example.com/ Bypassed: 200, direct

The uppercase HTTP_PROXY row is deliberate on curl’s part. Its manual says every variable works in either case except http_proxy, which is read in lowercase only. The reason, per the curl book, is CGI: a web server turns an incoming Proxy: request header into an HTTP_PROXY variable, so honouring it would let any client pick the proxy a server-side script uses. Other tools treat the variables differently, which is covered in HTTP_PROXY, HTTPS_PROXY and NO_PROXY explained. Check what is set before you debug anything else:

env | grep -i _proxy

Proving the proxy was used

Since curl 8.7.0, the %{proxy_used} write-out variable reports 1 when the transfer went through a proxy. It is the quickest way to see whether a NO_PROXY pattern matched:

$ curl -sS -o /dev/null -x http://user:pass@127.0.0.1:3128 -w '%{proxy_used}\n' https://example.com/
1
$ NO_PROXY=example.com https_proxy=http://127.0.0.1:3128 curl -sS -o /dev/null -w '%{proxy_used}\n' https://example.com/
0

One version difference showed up here. When the proxy connection itself failed, 8.7.1 printed proxy_used=0 and 8.23.0 printed proxy_used=1. Trust it on successful transfers only.

proxy_used tells you a proxy was involved, not which exit address the site saw. For that, ask a service that echoes your address back, and compare with the answer you get without the proxy:

curl -sS -x http://gw.example.net:8000 -U user:pass https://api.ipify.org

On a rotating gateway that answer describes one request. The next one may leave from a different exit node.

Where the time goes through a proxy

curl’s timing variables mean something slightly different once a proxy is involved, and the difference trips up anyone who reads time_connect as “time to reach the site”. We ran 10 requests to https://example.com/ in each mode with curl 8.23.0 and --http1.1:

Median of 10 requests per mode, curl 8.23.0, proxies on localhost, 21 October 2026 Drawn from the table below.
Median of 10 requests per mode, curl 8.23.0, proxies on localhost, 21 October 2026. Bar chart of time_connect (ms), time_appconnect (ms) by Mode.3 rows, drawn from the table that follows this chart.01020304050 msDirect · time_connect (ms): 9.629.62Direct · time_appconnect (ms): 30.3530.35DirectThrough Squid (HTTP CONNECT) · time_connect (ms): 0.230.23Through Squid (HTTP CONNECT) · time_appconnect (ms): 26.3326.33Through Squid (HTTP CONNECT)Through SOCKS5 (socks5h) · time_connect (ms): 0.280.28Through SOCKS5 (socks5h) · time_appconnect (ms): 40.7340.73Through SOCKS5 (socks5h)Median of 10 requests per mode, curl 8.23.0, proxies on localhost, 21 October 2026. Bar chart of time_connect (ms), time_appconnect (ms) by Mode.3 rows, drawn from the table that follows this chart.DirectDirect · time_connect (ms): 9.629.62Direct · time_appconnect (ms): 30.3530.35Through Squid (HTTPCONNECT)Through Squid (HTTP CONNECT) · time_connect (ms): 0.230.23Through Squid (HTTP CONNECT) · time_appconnect (ms): 26.3326.33Through SOCKS5(socks5h)Through SOCKS5 (socks5h) · time_connect (ms): 0.280.28Through SOCKS5 (socks5h) · time_appconnect (ms): 40.7340.730204060 ms
Mode time_connect (ms) time_appconnect (ms) time_total (ms)
Direct 9.62 30.35 45.68
Through Squid (HTTP CONNECT) 0.23 26.33 39.89
Through SOCKS5 (socks5h) 0.28 40.73 63.64

Through either proxy, time_connect fell to a fraction of a millisecond. That is not a faster network. curl’s manual defines it as the TCP connect “to the remote host (or proxy)”, and here the proxy was on the same machine. The proxy’s own connection to the site, the CONNECT or SOCKS exchange and the TLS handshake with the site all land in time_appconnect. So on a remote proxy, a high time_connect points at the path to the proxy, and a high time_appconnect with a low time_connect points at the proxy’s onward connection or the site’s TLS. Both proxies here were local, so treat these numbers as a demonstration of what the variables measure, not as a speed comparison.

curl -sS -o /dev/null -x http://gw.example.net:8000 -U user:pass \
  -w 'connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  https://example.com/

Retries that respect the server

--retry treats 408, 429 and the common 5xx answers (500, 502, 503, 504) as transient, and it obeys a Retry-After header when the server sends one. Against a test server answering 429 with Retry-After: 2, --retry 2 took 4.1 seconds on both builds: two waits of two seconds, then the final 429.

curl -sS -o /dev/null --retry 3 --retry-max-time 60 \
  -x http://gw.example.net:8000 -U user:pass \
  -w 'code=%{http_code} retries=%{num_retries}\n' https://example.com/

%{num_retries} exists from curl 8.9.0. On 8.7.1 the same command printed curl: unknown --write-out variable: 'num_retries'. --retry-max-time matters because Retry-After can also be a date, and a date can be hours away. The status codes themselves are covered in 407 vs 403 vs 429.

Testing a list of proxies

This loop reports the exit address for each working proxy and the exact curl error for each broken one. Keep the error text: as the table above shows, the exit code alone no longer separates a wrong password from a dead port.

#!/bin/bash
# check-proxies.sh: test every proxy in a file of host:port:user:pass lines
CURL=${CURL:-curl}
err=$(mktemp)
while IFS=: read -r host port user pass; do
  [ -z "$host" ] && continue
  ip=$("$CURL" -sS --max-time 15 --connect-timeout 5 \
        -x "http://$host:$port" --proxy-user "$user:$pass" \
        https://api.ipify.org 2>"$err")
  rc=$?
  if [ "$rc" -eq 0 ]; then
    printf '%-18s OK    exit_ip=%s\n' "$host:$port" "$ip"
  else
    printf '%-18s FAIL  exit=%s %s\n' "$host:$port" "$rc" "$(cat "$err")"
  fi
done < "${1:-proxies.txt}"
rm -f "$err"

Run against a good entry, a wrong password and a dead port with curl 8.23.0 (our own exit address redacted):

127.0.0.1:3128     OK    exit_ip=<redacted>
127.0.0.1:3128     FAIL  exit=7 curl: (7) CONNECT tunnel failed, response 407
127.0.0.1:3999     FAIL  exit=7 curl: (7) Failed to connect to api.ipify.org:443 over proxy 127.0.0.1 after 0 ms: Could not connect to server

--max-time stops one dead proxy stalling the run. Printing the exit address, not only a status, is what proves the proxy applied: a 200 that returns your own address means it did not.

Checking the exit country

Providers sell a country for the exit node, not for the gateway you dial. Check the exit:

curl -sS -x http://gw.example.net:8000 -U 'user-country-de:pass' \
  'http://ip-api.com/json/?fields=status,country,city,isp,as'

The -country-de suffix is an example. Every provider has its own username syntax for geo-targeting, and a malformed one can show up as a 407 or as the wrong country. Expect lookup services to disagree at city level. Country is the level worth checking.

Holding one address across requests

Providers that support sticky sessions typically do it through a session identifier in the username; the exact syntax varies. Keep cookies as well, because the site tracks both:

SESSION="s-$(openssl rand -hex 4)"
curl -sS -x http://gw.example.net:8000 -U "user-session-$SESSION:pass" -c jar.txt https://example.com/step-one
curl -sS -x http://gw.example.net:8000 -U "user-session-$SESSION:pass" -b jar.txt https://example.com/step-two

See rotating vs sticky sessions for when a flow needs this.

Headers, and what they do not change

When a page works in your browser and fails in curl, copy the browser’s request: developer tools, Network tab, right-click the request, Copy as cURL. Add -x and run it. If it now works, delete headers one at a time until it breaks; the last one you removed is the one the site checks.

Headers do not change curl’s TLS fingerprint, which the site sees before any header. Whether that matters depends on the site. We sent one plain curl 8.23.0 request and one with a Chrome User-Agent and Accept headers to three sites that answered default curl with 403. Two kept answering 403. The third returned its real home page with a 200, so for that site the User-Agent check was the whole block. One request each is an anecdote, not a rule, but it is a reason to try the cheap fix before buying a different proxy. The TLS ClientHello study and default request headers study show what curl sends compared with a browser.

Saving bandwidth on metered plans

On a per-gigabyte plan, request compression with --compressed, which also decompresses the answer. When you only need the status or a redirect, -I sends a HEAD request, which the server answers with headers only.

curl -sS -x http://gw.example.net:8000 -U user:pass --compressed https://example.com/page
curl -sS -x http://gw.example.net:8000 -U user:pass -I https://example.com/page

Through an HTTP proxy, -I output starts with the proxy’s own answer, so a script that reads the first line gets the wrong status. Both builds printed this for an HTTPS URL:

HTTP/1.1 200 Connection established

HTTP/2 200

The first block is the tunnel; the second is the site. Use -w '%{http_code}' if you only want the site’s status.

A checklist when a proxy “does not work”

  1. Run env | grep -i _proxy. Is something set that you did not expect?
  2. Run once with -v. Is there a CONNECT line at all?
  3. Print %{http_connect}. A 407 is credentials; a 403 or 503 there came from the proxy, not the site.
  4. Does an echo service return the proxy’s address or yours?
  5. Does the scheme match the port? A timeout on every request can mean socks5h:// pointed at an HTTP port.
  6. Does the same request succeed without the proxy? If not, the site is the problem.

The same checks in Python, with the exception each library raises, are in Python requests proxy setup. If you want to try a proxy without a terminal, the checker below opens one real connection through it.

Proxy checker

Live test

We open a real connection through your proxy and report what the exit node presented. Credentials are used for the single request and are never stored.

Also accepts user:pass@host:port. Public endpoints only.

Frequently asked questions

What is the difference between -x and --proxy in curl?
None. -x is the short form of --proxy. Both take a proxy URL with an optional scheme, credentials and port. Without a scheme curl assumes an HTTP proxy.
Why does curl exit with code 7 when my proxy password is wrong?
Since curl 8.20.0, any non-2xx answer to CONNECT returns exit code 7. Older builds, including the curl 8.7.1 that macOS ships, return 56 for the same failure. The message is identical in both: CONNECT tunnel failed, response 407.
Why does %{http_code} show 000 when the proxy rejects me?
For an HTTPS target the proxy's answer comes back to the CONNECT request, before anything reaches the site, so there is no site status to report. Use %{http_connect}, which holds the proxy's response code.
How do I stop curl leaking DNS through a SOCKS proxy?
Use socks5h:// instead of socks5://. Our logging SOCKS5 server received a bare IP address from socks5:// and the hostname from socks5h://. HTTP proxies do not have this problem for HTTPS targets, because the hostname travels inside the CONNECT request.
Does curl read the HTTP_PROXY environment variable?
Not in uppercase. curl reads http_proxy in lowercase only, because a CGI server turns a client's Proxy: header into an HTTP_PROXY variable. HTTPS_PROXY, ALL_PROXY and NO_PROXY work in either case.
How do I use a proxy password that contains @ or a colon?
Percent-encode it in the URL (@ becomes %40, a colon becomes %3A) or pass it with -U user:password, which splits on the first colon only. Unencoded, curl fails with exit 5 and Unsupported proxy syntax.

Sources

  1. curl manual: --proxy, --proxy-user, --retry, --write-out and environment variables
  2. Everything curl: proxy environment variables and the lowercase http_proxy rule
  3. curl pull request #21084: CONNECT failures return exit code 7 instead of 56
  4. curl 8.20.0 changelog
  5. curl release history (8.20.0 released 2026-04-29)
  6. RFC 9110 section 9.3.6: CONNECT
  7. RFC 1928: SOCKS Protocol Version 5
  8. RFC 1929: Username/Password Authentication for SOCKS V5

Read this page as Markdown · Quote it freely under CC BY 4.0 with a link back.