Tutorials 4 min read

Using curl with a Proxy: Every Flag You Need (2026 Guide)

curl is the fastest way to prove a proxy works. These are the flags and debugging habits worth knowing.

Before you wire a proxy into a scraper, a browser or an app, test it with curl. A curl proxy test takes five seconds and separates proxy problems from code problems. If curl works and your program doesn't, the bug is in your program. This guide covers every curl flag you'll realistically use with proxies, plus how to read the output when something fails.

The One-Line curl Proxy Test

curl -x http://USERNAME:[email protected]:8080 https://api.ipify.org

-x (or --proxy) sets the proxy. The response is the IP the target saw. Compare it to the address on our what is my IP tool without the proxy; if they differ, the proxy works.

Passing Credentials Separately with -U

Embedding credentials in the URL is convenient, but -U (or --proxy-user) keeps them separate and avoids URL-encoding problems:

curl -x http://global.nodeproxies.xyz:8080 -U 'USERNAME-country-de:PASSWORD' https://api.ipify.org

Single quotes stop your shell from interpreting characters like ! or $ in the password. If you do use the URL form, percent-encode special characters: @ becomes %40, : becomes %3A, # becomes %23.

SOCKS5 with curl

curl -x socks5h://USERNAME:[email protected]:1080 https://api.ipify.org

Note the h in socks5h. With socks5:// curl resolves the hostname on your machine and sends the IP to the proxy, which leaks your DNS lookups to your local resolver and can give a different, location-mismatched result. socks5h:// sends the hostname to the proxy so it resolves remotely. Use socks5h unless you have a reason not to. The broader trade-offs are in SOCKS5 vs HTTP proxies.

Environment Variables

curl reads proxy settings from the environment, which is handy for scripts:

export https_proxy='http://USERNAME:[email protected]:8080'
export http_proxy="$https_proxy"
export no_proxy='localhost,127.0.0.1'
curl https://api.ipify.org

curl only reads http_proxy in lowercase (for security reasons it ignores uppercase HTTP_PROXY), while HTTPS_PROXY works in either case. To bypass the environment for a single call, use --noproxy '*'.

Reading Verbose Output to Debug

-v shows the conversation with the proxy, which tells you exactly where things break:

curl -v -x http://USERNAME:[email protected]:8080 https://example.com -o /dev/null
  • "Failed to connect to global.nodeproxies.xyz port 8080": network problem between you and the proxy. Check firewalls and the port.
  • "CONNECT tunnel failed, response 407": the proxy rejected your credentials, or the plan isn't active. Walk through fixing proxy error 407.
  • "CONNECT tunnel failed, response 402": the plan has no bandwidth left.
  • "CONNECT tunnel failed, response 502" or 503: authentication passed but the proxy couldn't reach the target. Retry; it's usually the target or that exit IP.
  • "HTTP/1.1 200 Connection established" followed by a TLS error: the tunnel works; the problem is between you and the website.

Testing Rotation and Sticky Sessions

Without a session option, each request gets a new IP. A quick loop proves it:

for i in 1 2 3; do
  curl -s -x http://USERNAME:[email protected]:8080 https://api.ipify.org; echo
done

Add -session-test1-time-5 to the username and run the loop again: all three lines should show the same IP. Change test1 to test2 and you get a fresh one.

Other Useful Flags

  • --connect-timeout 10 and --max-time 30: stop hanging forever on a slow exit.
  • -w '%{time_connect} %{time_starttransfer} %{time_total}\n' -o /dev/null -s: measure where the latency is.
  • --proxy-header 'Name: value': send a header to the proxy only, not to the target.
  • -I: fetch headers only, useful for checking status codes without burning bandwidth.
  • --retry 3: retry transient failures automatically.

Saving Proxy Settings in .curlrc

If you test proxies all day, put the defaults in ~/.curlrc (_curlrc in your home folder on Windows) so every curl call uses them:

proxy = "http://global.nodeproxies.xyz:8080"
proxy-user = "USERNAME-country-us:PASSWORD"
connect-timeout = 10

Now plain curl https://api.ipify.org goes through the proxy. Two cautions: the file holds your password, so set its permissions to 600, and it affects every script on your account that calls curl. Run curl -q as the very first argument to ignore the file for one command, which is useful when a script mysteriously routes through a proxy you forgot about.

Comparing Countries Side by Side

Because the country lives in the username, a short loop shows how a page differs by market, which is handy for checking redirects or currency:

for c in us gb de; do
  printf '%s: ' "$c"
  curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
    -x http://global.nodeproxies.xyz:8080 -U "USERNAME-country-$c:PASSWORD" \
    https://example.com/
done

Testing NodeProxies with curl

After you create an account and buy a plan from pricing, copy credentials from the dashboard's proxy generator and run the one-line test above. If you need the same proxy in another format for a different tool, the proxy format converter rewrites it. A wider checklist is in how to test if a proxy is working.

FAQ

How do I use curl with a proxy that needs a username and password?

Use -x http://host:port -U 'user:pass', or embed the credentials as http://user:pass@host:port. Quote them so your shell doesn't change special characters.

What is the difference between socks5 and socks5h in curl?

socks5 resolves DNS locally and sends an IP to the proxy. socks5h sends the hostname so the proxy resolves it, which avoids DNS leaks.

Why does curl ignore my HTTP_PROXY variable?

curl only honours the lowercase http_proxy for plain HTTP. Use lowercase, or pass -x explicitly.

How do I make curl skip the proxy for one request?

Add --noproxy '*' to ignore proxy environment variables for that call.

NodeProxies

Ready to get started?

90M+ residential, mobile & datacenter proxies. Datacenter from $0.30/GB, residential from $0.42/GB. No contracts.

Create free account